home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-04 / dm3_doc.zip / DM.DOC < prev    next >
Text File  |  1990-08-02  |  174KB  |  4,927 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.             M Y C R O F T   R B B S   D O O R   I / O   L I B R A R Y
  31.  
  32.                                   Users Manual
  33.  
  34.                             for version 2.05 11/15/88
  35.  
  36.  
  37.  
  38.                                 I M P O R T A N T
  39.  
  40.      This document will be a floating document until all DMLIB 3.00
  41.      functions are implemented.  I will do my best to keep it up to date.
  42.      During the "floating" period there will be no attempt to keep the
  43.      page numbers up to date.
  44.  
  45.  
  46.  
  47.  
  48.  
  49.                           L I S T   O F   C H A N G E S
  50.  
  51.      The following is a listof changes asthey are made.  This will measure
  52.      ourprogress toward a completed 3.xx.
  53.  
  54.      04/06/90  Prelim 3.00 release
  55.                Interrupt or fossil driven i/o
  56.                Added format string to print_string()
  57.                Interrupt driven timer functions
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                            T H I N G S   T O   C O M E
  64.  
  65.      The following is a list of features/tasks to be completed in order of
  66.      precedence.  Not all things are on the list, just the stuff that is
  67.      upcomming soon.  Watch the BBS File Area #22 for updates to certain files
  68.      indicating an update.
  69.  
  70.      1. Convertion to new user & bbs data structures.  This will be mostly
  71.         an internal change but will have a few small effects on the "outside"
  72.         world.
  73.  
  74.      2. Re-vamp DMIO.  This will be split into several source files.  Also
  75.         additional functions will be added as time permits.
  76.  
  77.      3. Re-vamp DMBBS.  This will get rid of the need for the old NODES.BBS
  78.         file.  It will also add "local" login support for as many BBSs as
  79.         possible.   Additional BBSs will also be supported at that time
  80.         along with several "generic" options.
  81.  
  82.      4. Serialization and file protection utils & functions will be added.
  83.  
  84.      5. External message files & functions to support multi-lingual door
  85.         support (more on this soon).
  86.  
  87.      6. More stuff, to be announced later.....
  88.  
  89.      X. After DMLIB 3.xx is complete, we will start to work on DMGLIB.  This
  90.         will be an adon enhancement for allowing doors to run in graphics
  91.         modes.  A special term program will be provided to run on the users
  92.         side.  This term program will be generic and not "married" to a
  93.         single door.  Plans are to support MONO, CGA, EGA, VGA, and 8514 for
  94.         IBM terms, plus a MAC and MAC windows support for the MAC term
  95.         program.  For those of you who have access to and knowledge of other
  96.         computer systems, your help will be appreciated at that time.
  97.  
  98.  
  99.                                                                           i
  100.  
  101.                         T A B L E   O F   C O N T E N T S
  102.          (Note functions listed in lower case are either new or changed)
  103.  
  104.  
  105.      DISCLAIMER  . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii
  106.  
  107.      USER NOTICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii
  108.  
  109.      Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . . .   x
  110.  
  111.      I/O services  . . . . . . . . . . . . . . . . . . . . . . . . . . .   x
  112.           io_open  . . . . . . . . . . . . . . . . . . . . . . . . . . .   x
  113.           io_reopen. . . . .ReAquire comm port resources               */
  114.           io_close . . . . .Release comm port resources                */
  115.           dmcomm_init  . . .Initialize comm port resources             */
  116.           dmcomm_release . .Release comm port resources                */
  117.           dmcomm_status  . .Check low level input for data avail       */
  118.           dmcomm_regs  . . .Low level status registers                 */
  119.           dmcomm_input . . .Low level input                            */
  120.           dmcomm_output  . .Low level output                           */
  121.           dmcomm_wait  . . .Wait for output buffer empty               */
  122.           dmcomm_iflush  . .Flush low level input buffer               */
  123.           dmcomm_oflush  . .Flush low level output buffer              */
  124.           MODEM_CARRIER  . . . . . . . . . . . . . . . . . . . . . . . .   x
  125.           MODEM_STATUS . . . . . . . . . . . . . . . . . . . . . . . . .   x
  126.           MODEM_INPUT  . . . . . . . . . . . . . . . . . . . . . . . . .   x
  127.           MODEM_OUTPUT . . . . . . . . . . . . . . . . . . . . . . . . .   x
  128.           modem_wait . . . .Wait for output to complete                */
  129.           modem_iflush . . .Flush input buffer                         */
  130.           modem_oflush . . .Flush output buffer                        */
  131.           LOCAL_STATUS . . . . . . . . . . . . . . . . . . . . . . . . .   x
  132.           LOCAL_INPUT  . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  133.           LOCAL_CLS  . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  134.           LOCAL_OUTPUT . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  135.           LOCAL_BELL . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  136.           LOCAL_PRINT  . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  137.           local_wait . . . .Wait for output to complete                */
  138.           local_iflush . . .Flush input buffer                         */
  139.           local_oflush . . .Flush output buffer                        */
  140.           GET_LOCAL_CURSOR . . . . . . . . . . . . . . . . . . . . . . .  xx
  141.           SET_LOCAL_CURSOR . . . . . . . . . . . . . . . . . . . . . . .  xx
  142.           SET_LOCAL_BANNER . . . . . . . . . . . . . . . . . . . . . . .  xx
  143.           PUT_LOCAL_BANNER . . . . . . . . . . . . . . . . . . . . . . .  xx
  144.           IO_STATUS  . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  145.           IO_TESTS . . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  146.           IO_INPUT . . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  147.           IO_LINPUT  . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  148.           IO_LXINPUT . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  149.           IO_LEXINPUT  . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  150.           tio_input  . . . .Read char (timed)                          */
  151.           tio_linput . . . .Read line with line feed (timed)           */
  152.           tio_lxinput  . . .Read line without line feed (timed)        */
  153.           IO_PAUSE . . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  154.           EOL_DISPLAY  . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  155.           CLS_DISPLAY  . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  156.           CLS2_DISPLAY . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  157.           NO_CURSOR  . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  158.           SMALL_CURSOR . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  159.           MEDIUM_CURSOR  . . . . . . . . . . . . . . . . . . . . . . . .  xx
  160.           LARGE_CURSOR . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  161.           POSITION_CURSOR  . . . . . . . . . . . . . . . . . . . . . . .  xx
  162.  
  163.  
  164.  
  165.           PRINT_CHAR . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  166.           PRINT_CHARX  . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  167.           BACKUP . . . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  168.           print_string . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  169.           PRINT_METERED  . . . . . . . . . . . . . . . . . . . . . . . .  xx
  170.           PRINT_METEREDX . . . . . . . . . . . . . . . . . . . . . . . .  xx
  171.           io_wait  . . . . .Wait for output to complete                */
  172.           io_iflush  . . . .Flush input buffer                         */
  173.           io_oflush  . . . .Flush output buffer                        */
  174.           dmread_ports . . .Read i/o definition file                   */
  175.  
  176.      DOS services  . . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  177.           FILE_OPEN  . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  178.           FILE_CLOSE . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  179.           FILE_CHANGE  . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  180.           FILE_RESET . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  181.           set_dta  . . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  182.           GET_DTA  . . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  183.           FSEARCH  . . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  184.           FHIDE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  185.           FUNHIDE  . . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  186.  
  187.      BBS services  . . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  188.           read_bbs_info. . . . . . . . . . . . . . . . . . . . . . . . .  xx
  189.           RBBS_READ  . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  190.           QBBS_READ  . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  191.           PCBBS_READ . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  192.           PCBBS2_READ. . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  193.           WCBBS_READ . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  194.           GBBS_READ  . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  195.           WBBS_READ  . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  196.           sfbbs_read . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  197.           PAGE_OPERATOR  . . . . . . . . . . . . . . . . . . . . . . . .  xx
  198.           CHAT_MODE  . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  199.  
  200.      Door Monitor services . . . . . . . . . . . . . . . . . . . . . . .  xx
  201.           MON_READ . . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  202.           MON_WRITE  . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  203.           MON_PLAYER . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  204.           MON_EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  205.  
  206.      Time services . . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  207.           dmtimer_open . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  208.           dmtimer_close. . . . . . . . . . . . . . . . . . . . . . . . .  xx
  209.           delay  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  210.           sleep  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  211.           GET_DATE . . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  212.           CVT_DAYS . . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  213.           CUR_TIME . . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  214.           CVT_TIME . . . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  215.           TEST_TIMEOUT . . . . . . . . . . . . . . . . . . . . . . . . .  xx
  216.           TIME_CONTROLS. . . . . . . . . . . . . . . . . . . . . . . . .  xx
  217.           DAILY_CONTROLS . . . . . . . . . . . . . . . . . . . . . . . .  xx
  218.  
  219.      DM data structures. . . . . . . . . . . . . . . . . . . . . . . . .  xx
  220.           File access structures . . . . . . . . . . . . . . . . . . . .  xx
  221.           BBS access structures  . . . . . . . . . . . . . . . . . . . .  xx
  222.           Time control structures. . . . . . . . . . . . . . . . . . . . xxx
  223.           Monitor data structures. . . . . . . . . . . . . . . . . . . . xxx
  224.           User data structures . . . . . . . . . . . . . . . . . . . . . xxx
  225.  
  226.      In closing  . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxx
  227.  
  228.                                                                         iii
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.                                    DISCLAIMER
  247.                                    ----------
  248.  
  249.      This software  is provided  without any  guarantee, either expressed or
  250.      implied. All responsibilities for  its use  rest with  the user  of the
  251.      software and not the author.
  252.  
  253.  
  254.                                    USER NOTICE
  255.                                    -----------
  256.  
  257.      Now that  that is  out of  the way,  let me  say that  if you do find a
  258.      problem let me know by leaving me (the sysop) mail  on Mycroft  RBBS at
  259.      (408)927-0105 and I will try to help as much as possible.
  260.  
  261.      Also,  this  software  is  not  public  domain, freeware, or shareware,
  262.      distribution without the express permission of  the author  is strictly
  263.      forbidden (and a rotten thing too).
  264.  
  265.      Although not a requirement, I would appreciate if you would include the
  266.      following line as part of your game signon:
  267.  
  268.             I/O and BBS functions provided by the Mycroft DM library.
  269.  
  270.      Thanks and have fun.
  271.  
  272.  
  273.                                                                           1
  274.  
  275.      Introduction
  276.      ------------
  277.  
  278.      DM is designed  as  an  aid  to  programmers  who  wish  to  write door
  279.      applications for  RBBS and  PC-BOARD.   Two versions of the library are
  280.      provided.   The first  version is  compatible with  Microsoft C Version
  281.      4.x.  The second version is compatible with Microsoft C Version 5.x.
  282.  
  283.      DM functions  are broken  down into five primary catagories.  The first
  284.      provides a multitude of  I/O functions  for local,  remote, and virtual
  285.      consoles.   The second  provides an  easy interface  to DOS file access
  286.      with full SHARE.EXE compatibility.  The third set  of functions provide
  287.      access to  the BBS information for RBBS and PC-Board.  The fourth group
  288.      provides an interface with both Bob Wescott's door monitor and  the new
  289.      GMON  door  monitor.    The  last set provides some handy functions for
  290.      doing time maintenance in a BBS environment.
  291.  
  292.      This manual will detail  all of  the DM  functions along  with the data
  293.      structure  which  they  use.    The  following  files  should have been
  294.      included in your DM.ARC package:
  295.  
  296.                     DM.DOC         This document
  297.                     DM3.DOC        Eventual document ToC
  298.                     DM.LIB         Microsoft 4.x DM library
  299.                     DMDATA.H       Data structure include file
  300.                     DMFUNC.H       Function Prototypes
  301.                     MSTRMIND.C     Sample door application (source)
  302.                     MSTRMIND.HPN   Sample door application (help file)
  303.                     MSTRMIND.HPA   Sample door application (help file)
  304.                     MSTRMIND.HPG   Sample door application (help file)
  305.                     MSTRMIND.L     Sample door application (link script)
  306.                     TIMEGEN.EXE    Time control file compiler
  307.                     TIMES.DEF      Sample time control source file
  308.                     NODES.BBS      Sample node definition file
  309.  
  310.      Read through this manual once before attempting to write or  modify any
  311.      code  to  use  the  DM  functions.    After  that,  use the manual as a
  312.      reference guide.  Once you have conquered this task once, you will find
  313.      it easy to develop new doorware applications.
  314.  
  315.      Most of the functions are provided in a format similar to that provided
  316.      by Microsoft for detailing its library functions.
  317.  
  318.  
  319.                                                                           2
  320.  
  321.      I/O services
  322.      ------------
  323.  
  324.      The I/O services provide  local, remote,  and virtual  I/O.   They also
  325.      provide the programmer with functions to maintain the sysop's screen.
  326.  
  327.      Screen addressing  is based on the upper left hand corner of the screen
  328.      to be address (0,  0).   A (x,  y) address  mode is  used to  specify a
  329.      location on  the screen.   The  'x' value  is the column number, or the
  330.      horizontal axis, while the 'y' value is the row, or  line number.   The
  331.      routines do  not provide  error checking  on the  address given.  If an
  332.      address is given outside of  the  screen  space,  unpredictable results
  333.      could follow with the current and future screen address functions.
  334.  
  335.      The following section will detail all the I/O functions in the library.
  336.      Note that some of  these  functions  are  there  as  support  for other
  337.      functions.
  338.  
  339.  
  340.                                                                           3
  341.  
  342.      IO_OPEN
  343.      -------
  344.  
  345.      * Summary
  346.  
  347.      int   io_open(node);            /* Open the I/O library              */
  348.      int   node;                     /* The BBS node ID as passed in      */
  349.                                      /* via the command line argument     */
  350.  
  351.      * Description
  352.  
  353.      This function  is provide to establish the remote environment that will
  354.      be used by the I/O functions.  It must be  called before  any other I/O
  355.      function.
  356.  
  357.      This  function  expects  to  find  the  file NODES.BBS in the directory
  358.      specified by the data structure value 'bbs_dir'.
  359.  
  360.      If the node value passed in is '-1' then DM  will assume  it is running
  361.      in local mode.
  362.  
  363.      The DM  data structure 'remote_user' is set to 0 for a local connection
  364.      or to the comm port number for a remote connection.
  365.  
  366.  
  367.      * Return Value
  368.  
  369.       0    is returned if function completed successfully.
  370.      -1    is  returned  if  the  file  NODES.BBS  cannot  be  found  in the
  371.            directory specified in 'bbs_dir'.
  372.      -2    is returned  if the appropriate node line cannot be read from the
  373.            file NODES.BBS.
  374.      -3    is returned  if  an  invalid  device  is  specified  in  the file
  375.            NODES.BBS.
  376.  
  377.  
  378.                                                                           4
  379.  
  380.      * Example
  381.  
  382.      #include "dmfunc.h"
  383.      int node;                       /* node id number                   */
  384.      int rtc;                        /* return code value                */
  385.  
  386.      /*
  387.       * Test command line arg[1] for a node number
  388.       */
  389.  
  390.      if (argc < 2)                   /* if no node number...             */
  391.        io_open(-1);                  /* ...open as local console         */
  392.      else {                          /* otherwise...                     */
  393.        node = atoi(argv[1]);         /* convert node id to numeric       */
  394.        if (node > 1) {               /* if numeric...                    */
  395.          /*
  396.           * Process the open
  397.           */
  398.          rtc = io_open(node);        /* perform the open operation       */
  399.          switch (rtc) {              /* process return code              */
  400.            case  0:  /* all ok */
  401.                      break;
  402.  
  403.            case -1:  /* no nodes.bbs file */
  404.                      report_error("Error - Can't locate NODES.BBS\r\n");
  405.                      exit(1);
  406.                      break;
  407.  
  408.            case -2:  /* no node record in file */
  409.                      report_error("Error - No node record\r\n");
  410.                      exit(1);
  411.                      break;
  412.  
  413.            case -3:  /* illegal device name in file */
  414.                      report_error("Error - Illegal device\r\n");
  415.                      exit(1);
  416.                      break;
  417.  
  418.            default:  /* unexpected return code */
  419.                      report_error("Error - Can't locate NODES.BBS\r\n");
  420.                      exit(1);
  421.                      break;
  422.          }
  423.        } else {                      /* otherwise...                     */
  424.          report_error("Error - Illegal node parameter\r\n");
  425.          exit(1);
  426.        }
  427.      }
  428.  
  429.      /*
  430.       * DM is ready for I/O at this point
  431.       */
  432.  
  433.                                                                           5
  434.  
  435.      MODEM_CARRIER
  436.      -------------
  437.  
  438.      * Summary
  439.  
  440.      int   modem_carrier();          /* Test remote connection for        */
  441.                                      /* carrier detect.                   */
  442.  
  443.  
  444.      * Description
  445.  
  446.      This function will test the status of the comm port specified by the DM
  447.      data structure  'remote_user' for  carrier detect.   In  the event that
  448.      'remote_user' is 0 (a local connection) a detect status is simulated.
  449.  
  450.  
  451.      * Return Value
  452.  
  453.      0     is returned  if running  in local mode or if the remote comm port
  454.            still has an active carrier detect signal.
  455.      1     is returned if the remote  connection  has  been  dropped  by the
  456.            modem and carrier detect is no longer true.
  457.  
  458.  
  459.      * Example
  460.  
  461.      #include "dmfunc.h"
  462.  
  463.      /*
  464.       * Test if remote is still active
  465.       */
  466.  
  467.      if (modem_carrier()) {          /* if carrier detect lost..         */
  468.        report_error("Error - Loss of carrier detect,\r\n");
  469.        report_error("        Exiting to BBS.\r\n");
  470.        exit(2);
  471.      }
  472.  
  473.      /*
  474.       * All is still OK at this point
  475.       */
  476.  
  477.  
  478.                                                                           6
  479.  
  480.      MODEM_STATUS
  481.      ------------
  482.  
  483.      * Summary
  484.  
  485.      int   modem_status();           /* Test for remote char available    */
  486.  
  487.  
  488.      * Description
  489.  
  490.      This function will test the status of the comm port specified by the DM
  491.      data structure 'remote_user' for an incoming  keystroke.   If operating
  492.      strictly as  a local  connection, 'remote_user' is 0, a false (0) value
  493.      is returned.  Otherwise, if  a  character  is  ready  for  input,  2 is
  494.      returned.
  495.  
  496.  
  497.      * Return Value
  498.  
  499.      0     is returned  if running  in local mode or if no remote characters
  500.            are available.
  501.      2     is returned if a remote keystroke is available.
  502.  
  503.  
  504.      * See Also
  505.  
  506.            modem_input, local_status, local_input, io_status
  507.  
  508.  
  509.      * Example
  510.  
  511.      #include "dmfunc.h"
  512.      int key;                        /* incoming keystroke             */
  513.  
  514.      /*
  515.       * If remote keystroke is present, then read it
  516.       */
  517.  
  518.      key = 0;                        /* assume no input                  */
  519.      if (modem_status())             /* if a keystroke is present        */
  520.        key = modem_input();          /* get the remote keystroke         */
  521.  
  522.  
  523.                                                                           7
  524.  
  525.      MODEM_INPUT
  526.      -----------
  527.  
  528.      * Summary
  529.  
  530.      int   modem_input();            /* Read remote character             */
  531.  
  532.  
  533.      * Description
  534.  
  535.      This function will input a character  from the  comm port  specified by
  536.      the  DM  data  structure  'remote_user'  for an incoming keystroke.  If
  537.      operating strictly as a  local  connection,  'remote_user'  is  0, this
  538.      function should  not be called.  Always test for a character present by
  539.      using the 'modem_status' function first.
  540.  
  541.  
  542.      * Return Value
  543.  
  544.      The input character is returned.
  545.  
  546.  
  547.      * See Also
  548.  
  549.            modem_status, local_status, local_input
  550.  
  551.  
  552.      * Example
  553.  
  554.      #include "dmfunc.h"
  555.      int key;                        /* incoming keystroke             */
  556.  
  557.  
  558.      /*
  559.       * Loop until a remote char is present
  560.       */
  561.  
  562.      key = 0;                        /* assume no input                  */
  563.      while (modem_status() == 0);    /* loop till char is there          */
  564.        key = modem_input();          /* get the remote keystroke         */
  565.  
  566.  
  567.                                                                           8
  568.  
  569.      MODEM_OUTPUT
  570.      ------------
  571.  
  572.      * Summary
  573.  
  574.      int   modem_output(ch);         /* Write remote character            */
  575.      char  ch;                       /* Character to output               */
  576.  
  577.      * Description
  578.  
  579.      This function will output a character to the comm port specified by the
  580.      DM  data  structure  'remote_user'.    If operating strictly as a local
  581.      connection, 'remote_user' is 0,  this  function  will  take  no action.
  582.      Otherwise, the  character is  sent to  the comm port.  The character is
  583.      tested to see if it is a 'line feed', a hex 0x0A value.  If so then the
  584.      number of  nulls specified  by the  DM data  structure 'user_nulls' are
  585.      also sent to the comm port.
  586.  
  587.  
  588.      * Return Value
  589.  
  590.      This function always returns a 0.
  591.  
  592.  
  593.      * See Also
  594.  
  595.            local_output
  596.  
  597.  
  598.      * Example
  599.  
  600.      #include <string.h>
  601.      #include "dmfunc.h"
  602.      int   i;                        /* work variable                    */
  603.      char  message[] = "Hello\r\n";  /* a message                        */
  604.  
  605.      /*
  606.       * Print a string to remote stream
  607.       */
  608.  
  609.      for (i = 0; i < strlen(message); i++)
  610.        modem_output(message[i]);
  611.  
  612.  
  613.                                                                           9
  614.  
  615.      LOCAL_STATUS
  616.      ------------
  617.  
  618.      * Summary
  619.  
  620.      int   local_status();           /* Get local keyboard status         */
  621.  
  622.  
  623.      * Description
  624.  
  625.      This function will test  the  local  keyboard  for  the  presence  of a
  626.      keystroke.
  627.  
  628.  
  629.      * Return Value
  630.  
  631.      0     if no local keystroke is present
  632.      1     if a local keystroke is present
  633.  
  634.  
  635.      * See Also
  636.  
  637.            local_input, modem_status, modem_input, io_status
  638.  
  639.  
  640.      * Example
  641.  
  642.      #include "dmfunc.h"
  643.      int key;                        /* keyboard character               */
  644.  
  645.      /*
  646.       * Wait for local keystroke then input it
  647.       */
  648.  
  649.      while (local_status() == 0);    /* wait for a key                   */
  650.        key = local_input();          /* get the input                    */
  651.  
  652.  
  653.                                                                          10
  654.  
  655.      LOCAL_INPUT
  656.      -----------
  657.  
  658.      * Summary
  659.  
  660.      int local_input();              /* Get a local keyboard char         */
  661.  
  662.  
  663.      * Description
  664.  
  665.      This function  will wait  for a  local keystroke to be entered.  If the
  666.      keystroke is a special SysOp key then it will be  processed and  a null
  667.      character  will  be  returned.    Otherwise,  the  local  character  is
  668.      returned.  The following SysOp keys are supported:
  669.  
  670.            Alt F1       Eject user.
  671.            Right Arrow  Add 1 minute to users time.
  672.            Left Arrow   Subtract 1 minute from users time.
  673.            F4           Annoy toggle.
  674.            F6           Available toggle.
  675.            F9           Snoop toggle.
  676.            F10          Force CHAT mode.
  677.  
  678.  
  679.      * Return Value
  680.  
  681.      The function returns 0 if a SysOp key  is pressed,  else, the character
  682.      code striped to 7 bits is returned.
  683.  
  684.  
  685.      * See Also
  686.  
  687.            modem_input, local_status, modem_status
  688.  
  689.  
  690.      * Example
  691.  
  692.      #include "dmfunc.h"
  693.      int key;                        /* keyboard character               */
  694.  
  695.      /*
  696.       * Wait for local keystroke then input it
  697.       */
  698.  
  699.      while (local_status() == 0);    /* wait for a key                   */
  700.        key = local_input();          /* get the input                    */
  701.  
  702.  
  703.                                                                          11
  704.  
  705.      LOCAL_CLS
  706.      ---------
  707.  
  708.      * Summary
  709.  
  710.      int local_cls();                /* Clear the local display screen    */
  711.  
  712.  
  713.      * Description
  714.  
  715.      This function  will clear  the local  display screen  and set the local
  716.      cursor to (0,0).  This function has no effect on the remote terminal.
  717.  
  718.  
  719.      * Return Value
  720.  
  721.      This function always returns a 0.
  722.  
  723.  
  724.      * See Also
  725.  
  726.            cls_display, cls2_display, eol_display
  727.  
  728.  
  729.      * Example
  730.  
  731.      #include "dmfunc.h"
  732.      int key;                        /* keyboard character               */
  733.  
  734.      /*
  735.       * Clear the local display and then wait for a local keystroke
  736.       */
  737.  
  738.      local_cls();                    /* clear the display                */
  739.      key = local_input();            /* wait for and get local key       */
  740.  
  741.  
  742.                                                                          12
  743.  
  744.      LOCAL_OUTPUT
  745.      ------------
  746.  
  747.      * Summary
  748.  
  749.      int local_output(data);         /* Output char to local display      */
  750.      int data;                       /* Character to output               */
  751.  
  752.  
  753.      * Description
  754.  
  755.      This function will display the character passed to the function  at the
  756.      current display  position of  the local display.  No action is taken if
  757.      the DM data structure 'bbs_node_info.snoop' is set to ' 1'.
  758.  
  759.      If the output character is a line feed then this  function will perform
  760.      screen  scrolling  if  necessary  to  prevent  the  future  output from
  761.      entering the banner area.
  762.  
  763.      If the  output character is a bell character and  the DM data structure
  764.      remote_user is non zero, then the bell character is not output.
  765.  
  766.  
  767.      * Return Value
  768.  
  769.      This function always returns a 0.
  770.  
  771.  
  772.      * See Also
  773.  
  774.            modem_output
  775.  
  776.  
  777.      * Example
  778.  
  779.      #include <string.h>
  780.      #include "dmfunc.h"
  781.      int i;                          /* work variable                    */
  782.      char message[] = "This is it.\r\n";     /* a sample message         */
  783.  
  784.      /*
  785.       * Print a message on the local display
  786.       */
  787.  
  788.      for (i = 0; i < strlen(message); i++)
  789.        local_output(message[i]);
  790.  
  791.  
  792.                                                                          13
  793.  
  794.      LOCAL_BELL
  795.      ----------
  796.  
  797.      * Summary
  798.  
  799.      int local_bell();               /* Output bell to local display      */
  800.  
  801.  
  802.      * Description
  803.  
  804.      This function will output a bell character to the local dsiplay.
  805.  
  806.  
  807.      * Return Value
  808.  
  809.      This function always returns a 0.
  810.  
  811.  
  812.      * See Also
  813.  
  814.            modem_output
  815.  
  816.  
  817.      * Example
  818.  
  819.      #include <string.h>
  820.      #include "dmfunc.h"
  821.      int        i;
  822.  
  823.      /*
  824.       * Fatal crash error, alarm the SysOp
  825.       */
  826.  
  827.      local_print("Fatal error - Data files are corrupted!");
  828.      for(i = 0 ; i < 16 ; i++)
  829.        local_bell();
  830.  
  831.  
  832.                                                                          14
  833.  
  834.      LOCAL_PRINT
  835.      -----------
  836.  
  837.      * Summary
  838.  
  839.      int   local_print(string);      /* Output string to local display    */
  840.      char  *string;                  /* Pointer to output string          */
  841.  
  842.  
  843.      * Description
  844.  
  845.      This function will display  the string  passed to  the function  at the
  846.      current display  position of  the local display.  No action is taken if
  847.      the DM data structure 'bbs_node_info.snoop' is not set to ' 1'.
  848.  
  849.      If the output string contains a  line  feed,  then  this  function will
  850.      perform screen scrolling if necessary to prevent the future output from
  851.      entering the banner area.
  852.  
  853.  
  854.      * Return Value
  855.  
  856.      This function always returns a 0.
  857.  
  858.  
  859.      * See Also
  860.  
  861.            local_output,     modem_output,      print_char,     print_charx,
  862.            print_string, print_metered, print_meteredx
  863.  
  864.  
  865.      * Example
  866.  
  867.      #include "dmfunc.h"
  868.  
  869.      /*
  870.       * Print a message on the local display
  871.       */
  872.  
  873.      local_print("This is a local message\r\n");
  874.  
  875.  
  876.                                                                          15
  877.  
  878.      GET_LOCAL_CURSOR
  879.      ----------------
  880.  
  881.      * Summary
  882.  
  883.      int get_local_cursor(x, y);     /* Get the local cursor position     */
  884.      int *x;                         /* Pointer to x coordinate           */
  885.      int *y;                         /* Pointer to y coordinate           */
  886.  
  887.  
  888.      * Description
  889.  
  890.      This function  will return  the current  x &  y locations  of the local
  891.      displays cursor.  It is primarily used as an internal function, but may
  892.      be useful since both the local and remote cursor will usually be at the
  893.      same location.
  894.  
  895.  
  896.      * Return Value
  897.  
  898.      This function always returns a 0.
  899.  
  900.  
  901.      * See Also
  902.  
  903.            set_local_cursor, position_cursor
  904.  
  905.  
  906.      * Example
  907.  
  908.      #include "dmfunc.h"
  909.      int x, y;                       /* coordinates of the cursor        */
  910.  
  911.  
  912.      /*
  913.       * Print a message on the local display
  914.       */
  915.  
  916.      get_local_cursor(&x, &y);       /* save the current location        */
  917.      set_local_cursor(0, 24);        /* go to banner line
  918.      */
  919.      local_print("This is a local message\r\n");
  920.      set_local_cursor(x, y);         /* restore cursor location          */
  921.  
  922.  
  923.                                                                          16
  924.  
  925.      SET_LOCAL_CURSOR
  926.      ----------------
  927.  
  928.      * Summary
  929.  
  930.      int set_local_cursor(x, y);     /* Set the local cursor position     */
  931.      int x;                          /* X coordinate of new location      */
  932.      int y;                          /* Y coordinate of new location      */
  933.  
  934.  
  935.      * Description
  936.  
  937.      This function will move the local cursor to  the location  specified by
  938.      the x  & y  parameters.   It is primarily used as an internal function,
  939.      but may be useful to put a local message up at a desired location.
  940.  
  941.  
  942.      * Return Value
  943.  
  944.      This function always returns a 0.
  945.  
  946.  
  947.      * See Also
  948.  
  949.            get_local_cursor, position_cursor
  950.  
  951.  
  952.      * Example
  953.  
  954.      #include "dmfunc.h"
  955.      int x, y;                       /* coordinates of the cursor        */
  956.  
  957.  
  958.      /*
  959.       * Print a message on the local display
  960.       */
  961.  
  962.      get_local_cursor(&x, &y);       /* save the current location        */
  963.      set_local_cursor(0, 24);        /* go to banner line
  964.      */
  965.      local_print("This is a local message\r\n");
  966.      set_local_cursor(x, y);         /* restore cursor location          */
  967.  
  968.  
  969.                                                                          17
  970.  
  971.      SET_LOCAL_BANNER
  972.      ----------------
  973.  
  974.      * Summary
  975.  
  976.      int   set_local_banner(string, f, b);
  977.                                      /* Setup the local banner line       */
  978.      char  *string;                  /* Pointer to banner message         */
  979.      int   f;                        /* Foreground color of banner        */
  980.      int   b;                        /* Background color of banner        */
  981.  
  982.  
  983.      * Description
  984.  
  985.      This function will do all the setup work for the  banner line displayed
  986.      on the  SysOp's bottom  display line.   The  text string should usually
  987.      include the users name, the game  title, and  the game  version number.
  988.      The string is expected to be 80 characters in length.
  989.  
  990.      See  the  data  structures  &  includes  section  for  a description of
  991.      allowable foreground and background color definitions.
  992.  
  993.  
  994.      * Return Value
  995.  
  996.      This function always returns a 0.
  997.  
  998.  
  999.      * See Also
  1000.  
  1001.            put_local_banner
  1002.  
  1003.  
  1004.  
  1005.  
  1006.                                                                          18
  1007.  
  1008.      * Example
  1009.  
  1010.      #include "dmfunc.h"
  1011.      int i, x;                       /* work variables                   */
  1012.      char banner[81];                /* string to build banner in        */
  1013.      char title[] = "The Game";      /* title of the game                */
  1014.      char vers[] = "V1.00";          /* version number of the game       */
  1015.  
  1016.      /*
  1017.       * Setup & display the local banner
  1018.       */
  1019.  
  1020.      /* fill banner with spaces */
  1021.      for (i = 0; i < 80; i++)
  1022.        banner[i] = ' ';
  1023.  
  1024.      /* fill in user name */
  1025.      for (i = 0; i < strlen(user_name); i++)
  1026.        banner[i] = user_name[i];
  1027.  
  1028.      /* center the game title */
  1029.      x = 40 - (strlen(title) / 2);
  1030.      for (i = 0; i < strlen(title); i++)
  1031.        banner[x + i] = title[i];
  1032.  
  1033.      /* right justify version # */
  1034.      x = 79 - strlen(vers);
  1035.      for (i = 0; i < strlen(vers); i++)
  1036.        banner[x + i] = vers[i];
  1037.  
  1038.      set_local_banner(banner, WHITE, CYAN);
  1039.      put_local_banner();
  1040.  
  1041.  
  1042.                                                                          19
  1043.  
  1044.      PUT_LOCAL_BANNER
  1045.      ----------------
  1046.  
  1047.      * Summary
  1048.  
  1049.      int   put_local_banner();       /* Display banner on local screen    */
  1050.  
  1051.  
  1052.      * Description
  1053.  
  1054.      This function will display the previously  setup banner  on line  24 of
  1055.      the local  display.  The current cursor position is automatically saved
  1056.      and restored by the function.
  1057.  
  1058.      If the DM data structure 'bbs_node_info.snoop' is not set to ' 1', then
  1059.      no action will take place.
  1060.  
  1061.  
  1062.      * Return Value
  1063.  
  1064.      This function always returns a 0.
  1065.  
  1066.  
  1067.  
  1068.      * See Also
  1069.  
  1070.            set_local_banner
  1071.  
  1072.  
  1073.      * Example
  1074.  
  1075.        See example under set_local_banner.
  1076.  
  1077.                                                                          20
  1078.  
  1079.      IO_STATUS
  1080.      ---------
  1081.  
  1082.      * Summary
  1083.  
  1084.      int   io_status();              /* Get virtual console status        */
  1085.  
  1086.  
  1087.      * Description
  1088.  
  1089.      This  function  will  return  the  status  of the virtual console.  The
  1090.      virtual console may be either the local console, the remote console, or
  1091.      both,   depending   upon   the   states   of  the  DM  data  structures
  1092.      'remote_user' and 'bbs_node_info.snoop'.
  1093.  
  1094.  
  1095.      * Return Value
  1096.  
  1097.      0     if no data is available.
  1098.      1     if local data is available.
  1099.      2     if remote data is available.
  1100.  
  1101.  
  1102.      * See Also
  1103.  
  1104.            modem_status, local_status
  1105.  
  1106.  
  1107.      * Example
  1108.  
  1109.      #include "dmfunc.h"
  1110.      int status;                     /* virtual status                   */
  1111.      int key;                        /* virtual character                */
  1112.  
  1113.      /*
  1114.       * Wait for virtual char, then process it
  1115.       */
  1116.  
  1117.      status = 0;                     /* initialize                       */
  1118.  
  1119.      while (status == 0)             /* wait for a character             */
  1120.        status = io_status();
  1121.  
  1122.      if (status == 1)                /* get the input                    */
  1123.        key = local_input();
  1124.      else
  1125.        key = remote_input();
  1126.  
  1127.  
  1128.                                                                          21
  1129.  
  1130.      IO_TESTS
  1131.      --------
  1132.  
  1133.      * Summary
  1134.  
  1135.      int io_tests();                 /* Test virtual console for error    */
  1136.  
  1137.  
  1138.      * Description
  1139.  
  1140.      This function will return an error code if  there is  a problem  on the
  1141.      virtual  console.    It  tests  for  loss  of  carrier and time related
  1142.      problems.  The function never returns an error  if the  virtual console
  1143.      is only attached to the local console.
  1144.  
  1145.  
  1146.      * Return Value
  1147.  
  1148.       0    if no errors.
  1149.      -1    if carrier has been dropped.
  1150.      -2    if there has been no keyboard activity for 5 minutes.
  1151.      -3    if there is less than 5 minutes of connect time.
  1152.      -4    if all connect time has been used.
  1153.  
  1154.  
  1155.                                                                          22
  1156.  
  1157.      * Example
  1158.  
  1159.      #include "dmfunc.h"
  1160.      int status;                     /* virtual status                   */
  1161.  
  1162.      /*
  1163.       * Test for & report virtual errors
  1164.       */
  1165.  
  1166.      status = io_tests();            /* test for errors                  */
  1167.      switch (status) {               /* report if error                  */
  1168.        case 0: /* No errors */
  1169.          break;
  1170.  
  1171.        case -1:/* No carrier */
  1172.          local_print("Error - Loss of carrier\r\n");
  1173.          exit(1);
  1174.          break;
  1175.  
  1176.        case -2:/* No activity */
  1177.          local_print("Error - No activity for 5 minutes\r\n");
  1178.          exit(1);
  1179.          break;
  1180.  
  1181.        case -3:/* Time warning */
  1182.          local_print("Warning - Less than 5 minutes connect time\r\n");
  1183.          break;
  1184.  
  1185.        case -4:/* Time error */
  1186.          local_print("Error - All connect time has been used\r\n");
  1187.          exit(1);
  1188.          break;
  1189.      }
  1190.  
  1191.  
  1192.                                                                          23
  1193.  
  1194.      IO_INPUT
  1195.      --------
  1196.  
  1197.      * Summary
  1198.  
  1199.      int io_input();                 /* Get virtual console character     */
  1200.  
  1201.  
  1202.      * Description
  1203.  
  1204.      This function  will wait  for and  return a  character from the virtual
  1205.      console.  It tests for loss of carrier and time related problems.   The
  1206.      function never returns an error if the virtual console is only attached
  1207.      to the local console.
  1208.  
  1209.  
  1210.      * Return Value
  1211.  
  1212.      -1    if carrier has been dropped.
  1213.      -2    if there has been no keyboard activity for 5 minutes.
  1214.      -3    if there is less than 5 minutes of connect time.
  1215.      -4    if all connect time has been used.
  1216.            otherwise input character is returned.
  1217.  
  1218.  
  1219.      * See Also
  1220.  
  1221.            modem_input, local_input, modem_status, modem_status, io_status
  1222.  
  1223.  
  1224.                                                                          24
  1225.  
  1226.      * Example
  1227.  
  1228.      #include "dmfunc.h"
  1229.      int key;                        /* virtual input                    */
  1230.  
  1231.      /*
  1232.       * Get a char, test for & report virtual errors
  1233.       */
  1234.  
  1235.      key = io_input();               /* get a character                  */
  1236.      switch (status) {               /* report if error                  */
  1237.        case 0:   /* No errors */
  1238.          break;
  1239.  
  1240.        case -1:  /* No carrier */
  1241.          local_print("Error - Loss of carrier\r\n");
  1242.          exit(1);
  1243.          break;
  1244.  
  1245.        case -2:  /* No activity */
  1246.          local_print("Error - No activity for 5 minutes\r\n");
  1247.          exit(1);
  1248.          break;
  1249.  
  1250.        case -3:  /* Time warning */
  1251.          local_print("Warning - Less than 5 minutes connect time\r\n");
  1252.          break;
  1253.  
  1254.        case -4:  /* Time error */
  1255.          local_print("Error - All connect time has been used\r\n");
  1256.          exit(1);
  1257.          break;
  1258.  
  1259.        default:  /* Regular input */
  1260.          /* ... process input ... */
  1261.          break;
  1262.      }
  1263.  
  1264.  
  1265.                                                                          25
  1266.  
  1267.      IO_LINPUT, IO_LXINPUT, IO_LEXINPUT
  1268.      ----------------------------------
  1269.  
  1270.      * Summary
  1271.  
  1272.      int   io_linput(buff);          /* Get virtual console line with     */
  1273.                                      /*  terminating carriage return      */
  1274.  
  1275.      int   io_lxinput(buff);         /* Get virtual console line without  */
  1276.                                      /*  terminating carriage return      */
  1277.  
  1278.      int   io_lexinput(buff);        /* Get virtual console line without  */
  1279.                                      /*  terminating CR or echo           */
  1280.  
  1281.      char  buff[80];                 /* 80 character line buffer          */
  1282.  
  1283.  
  1284.      * Description
  1285.  
  1286.      All three functions will wait  for and return a  line of data from  the
  1287.      virtual console.   It tests  for loss of  carrier and any time  related
  1288.      problems.   The function never returns an error if the  virtual console
  1289.      is only attached to the local console.
  1290.  
  1291.      Characters are echoed to the virtual  console as entered in all but the
  1292.      io_lexinput function. Carriage return line feed sequence is echoed upon
  1293.      receipt of a terminating carriage  return character with io_linput, but
  1294.      not with io_lxinput  or io_lexinput.   These functions  support editing
  1295.      using the backspace key and calls the virtual I/O functions for support
  1296.      of the SysOp keys.
  1297.  
  1298.  
  1299.      * Return Value
  1300.  
  1301.      Both functions  always returns  a 0,  but the return string may contain
  1302.      one of the following error strings:
  1303.  
  1304.            "~NO_CARRIER"
  1305.            "~NOT_ACTIVE"
  1306.            "~TIME_WARNING"
  1307.            "~TIMEOUT"
  1308.  
  1309.      If none of these strings are returned then the users  input is returned
  1310.      as a null terminated string.
  1311.  
  1312.  
  1313.      * See Also
  1314.  
  1315.            modem_input, local_input
  1316.  
  1317.  
  1318.                                                                          26
  1319.  
  1320.      * Example
  1321.  
  1322.      #include "dmfunc.h"
  1323.      char buffer[80];                /* input buffer                     */
  1324.  
  1325.      /*
  1326.       * Get a command string, test for & report virtual errors
  1327.       */
  1328.  
  1329.      io_linput(buffer);              /* get a command string             */
  1330.      if (strcmp(buffer, "~NO_CARRIER") == 0) {
  1331.        /* Loss of carrier */
  1332.        local_print("Error - Loss of carrier\r\n");
  1333.        exit(1);
  1334.      } else
  1335.        if (strcmp(buffer, "~NOT_ACTIVE") == 0) {
  1336.         /* Lack of activity */
  1337.         local_print("Error - No activity for 5 minutes\r\n");
  1338.          exit(1);
  1339.        } else
  1340.          if (strcmp(buffer, "~TIME_WARNING") == 0) {
  1341.           /* Running out of time */
  1342.           local_print("Warning - Less than 5 minutes connect time\r\n");
  1343.            exit(1);
  1344.          } else
  1345.            if (strcmp(buffer, "~TIMEOUT") == 0) {
  1346.             /* Out of time */
  1347.              local_print("Error - All connect time has been used\r\n");
  1348.              exit(1);
  1349.            } else {
  1350.              /* ... process user command ... */
  1351.            }
  1352.  
  1353.  
  1354.                                                                          27
  1355.  
  1356.      IO_PAUSE
  1357.      --------
  1358.  
  1359.      * Summary
  1360.  
  1361.      int   io_pause(string, flag);   /* Print a string & wait for ENTER   */
  1362.      char  *string;                  /* Pointer to message to output      */
  1363.      int   flag;                     /* Centering flag  0 = Left margin   */
  1364.                                      /*                 1 = Centered      */
  1365.  
  1366.  
  1367.      * Description
  1368.  
  1369.      This function  will display  a message  on the virtual console and then
  1370.      wait for an ENTER  key to  be entered  from the  virtual console.   The
  1371.      function will  abort in  the event of loss of carrier or timeouts.  The
  1372.      flag controls whether or not to center the message.
  1373.  
  1374.      After the ENTER key is received, a carriage  return line  feed sequence
  1375.      is issued  if the remote console is a printing device or it will backup
  1376.      and erase the message if not.
  1377.  
  1378.  
  1379.      * Return Value
  1380.  
  1381.      This function always returns a 0.
  1382.  
  1383.  
  1384.      * Example
  1385.  
  1386.      #include "dmfunc.h"
  1387.  
  1388.      /*
  1389.       * Print a prompt to continue (centered)
  1390.       */
  1391.  
  1392.      io_pause("Press [ENTER] to continue...", 1);
  1393.  
  1394.  
  1395.                                                                          28
  1396.  
  1397.      EOL_DISPLAY
  1398.      -----------
  1399.  
  1400.      * Summary
  1401.  
  1402.      int   eol_display();            /* Erase virtual to end of line      */
  1403.  
  1404.  
  1405.      * Description
  1406.  
  1407.      This function will erase  the virtual  console from  the current cursor
  1408.      position to  the end  of line.  This function only works if the DM data
  1409.      structure 'user_graphics' is set to 2 indicating ANSI support.
  1410.  
  1411.  
  1412.      * Return Value
  1413.  
  1414.      This function always returns a 0.
  1415.  
  1416.  
  1417.      * See Also
  1418.  
  1419.            cls_display, cls2_display, local_cls
  1420.  
  1421.  
  1422.      * Example
  1423.  
  1424.      #include "dmfunc.h"
  1425.      int i;
  1426.  
  1427.      /*
  1428.       * Erase the message section of the virtual console
  1429.       * (lines 18-22 are erased (note screen is base 0))
  1430.       */
  1431.  
  1432.      for (i = 17; i < 22; i++) {
  1433.        position_cursor(0, i);
  1434.        eol_display();
  1435.      }
  1436.  
  1437.  
  1438.                                                                          29
  1439.  
  1440.      CLS_DISPLAY, CLS2_DISPLAY
  1441.      -------------------------
  1442.  
  1443.      * Summary
  1444.  
  1445.      int cls_display();              /* Clear virtual display             */
  1446.  
  1447.  
  1448.      * Description
  1449.  
  1450.      These functions will  erase  the  virtual  console.    If  the  DM data
  1451.      structure 'user_graphics' is set to 2 then the screen is cleared via an
  1452.      ANSI escape sequence.   Otherwise, cls_display  sends 25  line feeds to
  1453.      the display, and cls2_display sends 3 line feeds.
  1454.  
  1455.  
  1456.      * Return Value
  1457.  
  1458.      These functions always returns a 0.
  1459.  
  1460.  
  1461.      * See Also
  1462.  
  1463.            cls2_display, local_cls, eol_display
  1464.  
  1465.  
  1466.      * Example
  1467.  
  1468.      #include "dmfunc.h"
  1469.  
  1470.      /*
  1471.       * Clear the screen
  1472.       */
  1473.  
  1474.      cls_display();
  1475.  
  1476.  
  1477.                                                                          30
  1478.  
  1479.      NO_CURSOR, SMALL_CURSOR, MEDIUM_CURSOR, LARGE_CURSOR
  1480.      ----------------------------------------------------
  1481.  
  1482.      * Summary
  1483.  
  1484.      int no_cursor();                /* Turn off local cursor             */
  1485.  
  1486.      int small_cursor();             /* Set local cursor to underline     */
  1487.  
  1488.      int medium_cursor();            /* Set local cursor to half block    */
  1489.  
  1490.      int large_cursor();             /* Set local cursor to full block    */
  1491.  
  1492.  
  1493.      * Description
  1494.  
  1495.      These functions  will set  the cursor  size on  the local console.  The
  1496.      remote console is totally unaffected by these functions.
  1497.  
  1498.  
  1499.      * Return Value
  1500.  
  1501.      These functions always returns a 0.
  1502.  
  1503.  
  1504.      * Example
  1505.  
  1506.      #include "dmfunc.h"
  1507.  
  1508.      /*
  1509.       * Turn off local cursor
  1510.       */
  1511.  
  1512.      no_cursor();
  1513.  
  1514.  
  1515.                                                                          31
  1516.  
  1517.      POSITION_CURSOR
  1518.      ---------------
  1519.  
  1520.      * Summary
  1521.  
  1522.      int position_cursor(x, y);      /* Position virtual cursor           */
  1523.      int x;                          /* X coordinate (base 0)  Column     */
  1524.      int y;                          /* Y coordinate (base 0)  Line       */
  1525.  
  1526.  
  1527.      * Description
  1528.  
  1529.      This function will position  the cursor  on the  virtual console.   The
  1530.      function only  works if the DM data structure 'user_graphics' is set to
  1531.      2.  Otherwise, the function does  nothing.   The cursor  positioning is
  1532.      done via an ANSI escape sequence.
  1533.  
  1534.  
  1535.      * Return Value
  1536.  
  1537.      This function always returns a 0.
  1538.  
  1539.  
  1540.      * See Also
  1541.  
  1542.            set_local_cursor, get_local_cursor
  1543.  
  1544.  
  1545.      * Example
  1546.  
  1547.      #include "dmfunc.h"
  1548.  
  1549.      /*
  1550.       * Issue an error message on line 24 of display
  1551.       */
  1552.  
  1553.      position_cursor(0, 23);         /* set position on 24th line        */
  1554.      print_string("Error - Illegal command.");
  1555.  
  1556.  
  1557.                                                                          32
  1558.  
  1559.      PRINT_CHAR, PRINT_CHARX
  1560.      -----------------------
  1561.  
  1562.      * Summary
  1563.  
  1564.      int   print_char(character);    /* Print char to virtual display     */
  1565.  
  1566.      int   print_charx(character);   /* Print char to virtual display     */
  1567.                                      /* without backspace interpretation. */
  1568.  
  1569.      char  character;                /* Character to print                */
  1570.  
  1571.  
  1572.      * Description
  1573.  
  1574.      Both  functions  will  display  the  passed in character at the current
  1575.      cursor position on the virtual display.  Backspace  interpretation (hex
  1576.      code  08)   is  performed   with  print_char,  while  it  is  not  with
  1577.      print_charx.  If the remote  display  is  active  and  a  line  feed is
  1578.      issued, then  the appropriate  number of  nulls are sent if the DM data
  1579.      structure 'mon_nulls' is set to a value greater than 0.
  1580.  
  1581.      The DM data structure 'user_caps' is also checked to see  if the output
  1582.      character must be forced to upper case.
  1583.  
  1584.  
  1585.      * Return Value
  1586.  
  1587.      This function always returns a 0.
  1588.  
  1589.  
  1590.      * Example
  1591.  
  1592.      #include "dmfunc.h"
  1593.      int i;                          /* work variable                    */
  1594.      char message[] = "Hello";       /* a sample message                 */
  1595.  
  1596.      /*
  1597.       * Issue a message at current position
  1598.       */
  1599.  
  1600.      for (i = 0; i < strlen(message); i++)
  1601.        print_char(message[i]);
  1602.  
  1603.  
  1604.                                                                          33
  1605.  
  1606.      BACKUP
  1607.      ------
  1608.  
  1609.      * Summary
  1610.  
  1611.      int backup(count);              /* Issue bksps to virtual display    */
  1612.      int count;                      /* Number of backspaces to issue     */
  1613.  
  1614.  
  1615.      * Description
  1616.  
  1617.      This function  will erase character from the current cursor position of
  1618.      the virtual display.
  1619.  
  1620.  
  1621.      * Return Value
  1622.  
  1623.      This function always returns a 0.
  1624.  
  1625.  
  1626.      * Example
  1627.  
  1628.      #include "dmfunc.h"
  1629.      char message[] = "Error - bad command";
  1630.  
  1631.      /*
  1632.       * Issue a self destructive error message
  1633.       */
  1634.  
  1635.      position_cursor(0, 24);         /* go to desired location           */
  1636.      print_string(message);          /* issue the message                */
  1637.      sleep(3);                       /* delay                            */
  1638.      backup(strlen(message);         /* now destroy it                   */
  1639.  
  1640.  
  1641.                                                                          34
  1642.  
  1643.      PRINT_STRING
  1644.      ------------
  1645.  
  1646.      * Summary
  1647.  
  1648.      int   print_string(string);     /* Issue message to virtual display  */
  1649.      char  *message;                 /* Pointer to message to print       */
  1650.  
  1651.  
  1652.      * Description
  1653.  
  1654.      This function will display  the passed  string on  the virtual console.
  1655.      Backspace and line feed interpretation are performed.
  1656.  
  1657.  
  1658.      * Return Value
  1659.  
  1660.      This function always returns a 0.
  1661.  
  1662.  
  1663.      * Example
  1664.  
  1665.      #include <stdio.h>
  1666.      #include "dmfunc.h"
  1667.      int eline;                      /* error line number                */
  1668.      int error;                      /* error code                       */
  1669.      char message[80];               /* message buffer                   */
  1670.  
  1671.      /*
  1672.       * Issue a self destructive error message
  1673.       */
  1674.  
  1675.      position_cursor(0, 24);         /* go to desired location           */
  1676.      sprintf(message, "Error %d in line %d", error, eline);
  1677.      print_string(message);          /* issue the message                */
  1678.      sleep(3);                       /* delay                            */
  1679.      backup(strlen(message);         /* now destroy it                   */
  1680.  
  1681.  
  1682.                                                                          35
  1683.  
  1684.      PRINT_METERED
  1685.      -------------
  1686.  
  1687.      * Summary
  1688.  
  1689.      int   print_metered(line, str, buff);
  1690.                                      /* Issue message to virtual display  */
  1691.      int   *line;                    /* Pointer to line counter           */
  1692.      char  *str;                     /* Pointer to message to print       */
  1693.      char  *buff;                    /* Pointer to 80 char input buffer   */
  1694.  
  1695.  
  1696.      * Description
  1697.  
  1698.      This function will display the passed in string on the virtual console.
  1699.      In addition, it will allow the output to be metered so that the display
  1700.      will pause and allow the user to read the information without it having
  1701.      scrolled of the screen.  It is designed primarily to be used  with help
  1702.      and instruction files.
  1703.  
  1704.      After displaying  the message, the line count is incremented.  If it is
  1705.      greater than or equal to  one  less  than  the  value  in  the  DM data
  1706.      structure 'user_page', then the following message is displayed centered
  1707.      on the virtual console:
  1708.  
  1709.                              Continue [Y], N, NS...
  1710.  
  1711.      The program will then pause and  wait for  a response  from the virtual
  1712.      console.    The  responses  will  determine  the  return  code from the
  1713.      function.
  1714.  
  1715.  
  1716.      * Return Value
  1717.  
  1718.       0    is returned is the user entered a carriage return or a Y.
  1719.       1    is returned is the user entered a NS.
  1720.       2    is returned is the user entered a N.
  1721.      -1    is returned in all other cases.
  1722.  
  1723.  
  1724.      * See Also
  1725.  
  1726.            print_meteredx
  1727.  
  1728.                                                                          36
  1729.  
  1730.      * Example
  1731.  
  1732.      #include "dmfunc.h"
  1733.      int control;                    /* loop output control              */
  1734.      int line;                       /* line counter                     */
  1735.      int max_line;                   /* total lines to output            */
  1736.      int rtc;                        /* return code                      */
  1737.      char help_info[100][80];        /* help information array           */
  1738.      char buffer[80];                /* 80 char input buffer             */
  1739.  
  1740.      /*
  1741.       * Display the help information
  1742.       */
  1743.  
  1744.      control = 0;                    /* set loop controller              */
  1745.      line = 0;                       /* start with line 0                */
  1746.      max_line = 0;
  1747.      while ((control < 2) && (max_line < 100)) {
  1748.        /* Print function is dependant on
  1749.         * whether NS has been pressed or not
  1750.         */
  1751.        if (control)                  /* if the NS has been entered       */
  1752.          print_string(message[max_line]);
  1753.        else                          /* otherwise                        */
  1754.          rtc = print_metered(&line, message[max_line], buffer);
  1755.  
  1756.        if (rtc == 1)                 /* NS has been pressed              */
  1757.          control = 1;
  1758.        else
  1759.          if (rtc == 2)               /* N has been pressed, abort        */
  1760.            control = 2;
  1761.  
  1762.        /*
  1763.         * Here a call to a error checking routine
  1764.         * is made to watch for loss of carrier
  1765.         * or timeouts.
  1766.         */
  1767.        if (check_error(buffer))
  1768.          exit(1);
  1769.  
  1770.        /*
  1771.         * Else do next line
  1772.         */
  1773.  
  1774.        max_line++;
  1775.      }
  1776.  
  1777.  
  1778.                                                                          37
  1779.  
  1780.      PRINT_METEREDX
  1781.      --------------
  1782.  
  1783.      * Summary
  1784.  
  1785.      int   print_meteredx(line, str, buf);
  1786.                                      /* Issue message to virtual display  */
  1787.      int   *line;                    /* Pointer to line counter           */
  1788.      char  *str;                     /* Pointer to message to print       */
  1789.      char  *buf;                     /* Pointer to 80 char input buffer   */
  1790.  
  1791.  
  1792.      * Description
  1793.  
  1794.      This function will display the passed in string on the virtual console.
  1795.      In addition, it will allow the output to be metered so that the display
  1796.      will pause and allow the user to read the information without it having
  1797.      scrolled off the screen.  It is designed primarily to be used with help
  1798.      and instruction files.
  1799.  
  1800.      Unlike the 'print_metered' function, this function does not  supply the
  1801.      user with the ability to turn off the metering or to abort the display.
  1802.      The DM data structure 'user_page' is also used here to monitor the line
  1803.      count.  The metering pause message for this function is:
  1804.  
  1805.                           Press [ENTER] to continue...
  1806.  
  1807.      The program  will then  pause and  wait for a response from the virtual
  1808.      console.    The  responses  will  determine  the  return  code  for the
  1809.      function.
  1810.  
  1811.  
  1812.      * Return Value
  1813.  
  1814.       0    is returned if the user entered a carriage return.
  1815.      -1    is returned in all other cases.
  1816.  
  1817.  
  1818.  
  1819.  
  1820.                                                                          38
  1821.  
  1822.      * Example
  1823.  
  1824.      int print_meteredx();           /* print on the virtual display     */
  1825.      int control;                    /* loop output control              */
  1826.      int line;                       /* line counter                     */
  1827.      int max_line;                   /* total lines to output            */
  1828.      int rtc;                        /* return code                      */
  1829.      char login_info[100][80];       /* login information array          */
  1830.      char buffer[80];                /* 80 char input buffer             */
  1831.  
  1832.      /*
  1833.       * Display the login information
  1834.       */
  1835.      control = 0;                    /* set loop controller              */
  1836.      line = 0;                       /* start with line 0                */
  1837.      max_line = 0;
  1838.  
  1839.      while ((control == 0) && (max_line < 100)) {
  1840.        rtc = print_metered(&line, message[max_line], buffer);
  1841.  
  1842.        /*
  1843.         * Here a call to a error checking routine
  1844.         * is made to watch for loss of carrier
  1845.         * or timeouts.
  1846.         */
  1847.  
  1848.        if (rtc) {
  1849.          if (check_error(buffer))
  1850.            exit(1);
  1851.        }
  1852.  
  1853.        /*
  1854.         * Else do next line
  1855.         */
  1856.  
  1857.        max_line++;
  1858.      }
  1859.  
  1860.  
  1861.                                                                          39
  1862.  
  1863.      DOS services
  1864.      ------------
  1865.  
  1866.      The DOS  services provide the programmer with a simple way to implement
  1867.      SHARE.EXE compatible code  for  multi-node  BBS.    Also  functions are
  1868.      provided to allow searching the disk for files.
  1869.  
  1870.      All file  access is done via a file structure.  The FS access structure
  1871.      is detailed in the chapter on DM data structures.
  1872.  
  1873.      Files should always be open for  read-only unless  the open  is to just
  1874.      write to  the file.  Whenever you need to write to a file that is open,
  1875.      make a call to the 'file_change' function, do the write, and then reset
  1876.      the file back to read only using the 'file_reset' function.
  1877.  
  1878.      Files are always opened in both direct and stream mode and thus you may
  1879.      use whichever mode  you prefer when accessing them.   It is recommended
  1880.      that you access files in  direct mode whenevr possible though as stream
  1881.      I/O is not guaranteed to be acurate under shared file access.
  1882.  
  1883.      The following section will detail all the DOS functions in the library.
  1884.      Note  that  some  of  these  functions  are  there as support for other
  1885.      functions.
  1886.  
  1887.  
  1888.  
  1889.                                                                          40
  1890.  
  1891.      FILE_OPEN
  1892.      ---------
  1893.  
  1894.      * Summary
  1895.  
  1896.      int file_open(file, rw, mode, cf);
  1897.                                      /* Open a file for sharing           */
  1898.      FS  *file;                      /* Pointer to file structure         */
  1899.      int rw;                         /* Read/write access control         */
  1900.                                      /*   (0) FREAD    read only          */
  1901.                                      /*   (1) FMODIFY  read/write         */
  1902.                                      /*   (2) FAPPEND  append             */
  1903.                                      /*   (3) FWRITE   write only         */
  1904.      int mode;                       /* File mode access control          */
  1905.                                      /*   (0) FTEXT    text file          */
  1906.                                      /*   (1) FBINARY  binary file        */
  1907.      int cf;                         /* File creation control             */
  1908.                                      /*   (0) FNOCREATE                   */
  1909.                                      /*   (1) FCREATE                     */
  1910.  
  1911.  
  1912.      * Description
  1913.  
  1914.      This function is the most complex  of the  file sharing  functions.  In
  1915.      general, the  filename is  copied to  the appropriate section of the FS
  1916.      structure and the function call is made.
  1917.  
  1918.      If the FNOCREATE parameter is passed, then the file must  exist on disk
  1919.      or  the  function  will  fail.    If the FCREATE parameter is used, the
  1920.      functions action will be based on  the 'rw'  parameter.   The following
  1921.      actions are taken based on this parameter:
  1922.  
  1923.            FREAD    Open existing file, error if not present.
  1924.            FMODIFY  Open existing file, create if not present.
  1925.            FAPPEND  Open existing file, create if not present.
  1926.            FWRITE   Delete any existing file, create new file.
  1927.  
  1928.      It  is  suggested  that  the  files  used for read/write or read/append
  1929.      access be opened using the FREAD  parameter and  that the 'file_change'
  1930.      and 'file_reset'  functions be  used when it comes time to write to it.
  1931.      This method will provide the proper interaction with SHARE.EXE and will
  1932.      avoid other BBS nodes from being denied access to the file.
  1933.  
  1934.      Also, when modifying sections of a record, the record should be re-read
  1935.      after the 'file_change' function is called  to guarantee  the integrity
  1936.      of the file.
  1937.  
  1938.  
  1939.  
  1940.  
  1941.                                                                          41
  1942.  
  1943.      * Return Value
  1944.  
  1945.       0    is returned if function completed successfully.
  1946.      -1    is returned if an attempt made to create an existing file.
  1947.      -2    is returned if no file handles are available.
  1948.      -3    is returned  if an  attempt is  made to open an existing file and
  1949.            the file cannot be found.
  1950.      -4    is returned if the file cannot  be successfully  opened in stream
  1951.            access mode.
  1952.      -5    is returned  if the  file is  share locked.   This return code is
  1953.            only returned after several attempts were made to  open the file.
  1954.            This usually  indicates that  either a program section is leaving
  1955.            the file set for writing too long or has failed to make  the call
  1956.            to 'file_reset'.
  1957.  
  1958.  
  1959.      * See Also
  1960.  
  1961.            file_close, file_change, file_reset
  1962.  
  1963.  
  1964.      * Example
  1965.  
  1966.        See  the  example  in  file_reset  for  proper  use  of  all the file
  1967.        functions.
  1968.  
  1969.                                                                          42
  1970.  
  1971.      FILE_CLOSE
  1972.      ----------
  1973.  
  1974.      * Summary
  1975.  
  1976.      int file_close(file);           /* Close a shared file               */
  1977.      FS  *file;                      /* Pointer to file structure         */
  1978.  
  1979.  
  1980.      * Description
  1981.  
  1982.      This function is used to close a file that was open in  share mode. The
  1983.      file is closed for both direct and stream access.
  1984.  
  1985.  
  1986.      * Return Value
  1987.  
  1988.      This function always returns 0.
  1989.  
  1990.  
  1991.      * See Also
  1992.  
  1993.            file_open, file_change, file_reset
  1994.  
  1995.  
  1996.      * Example
  1997.  
  1998.      FS  rfile;                                /* file access structure   */
  1999.      int file_close();                         /* close a shared file     */
  2000.  
  2001.  
  2002.      /*
  2003.       * Close the help file
  2004.       */
  2005.  
  2006.      file_close(&rfile);
  2007.  
  2008.  
  2009.                                                                          43
  2010.  
  2011.      FILE_CHANGE
  2012.      -----------
  2013.  
  2014.      * Summary
  2015.  
  2016.      int   file_change(file, rw, md, cf);
  2017.                                      /* Change shared file access         */
  2018.      FS    *file;                    /* Pointer to file structure         */
  2019.      int   rw;                       /* Read/write access control         */
  2020.                                      /*   (0) FREAD    read only          */
  2021.                                      /*   (1) FMODIFY  read/write         */
  2022.                                      /*   (2) FAPPEND  append             */
  2023.                                      /*   (3) FWRITE   write only         */
  2024.      int   md;                       /* File mode access control          */
  2025.                                      /*   (0) FTEXT    text file          */
  2026.                                      /*   (1) FBINARY  binary file        */
  2027.      int cf;                         /* File creation control             */
  2028.                                      /*   (0) FNOCREATE                   */
  2029.                                      /*   (1) FCREATE                     */
  2030.  
  2031.  
  2032.      * Description
  2033.  
  2034.      Once you  have mastered  the 'file_open'  function, you  will find this
  2035.      function  simple  to  use.    All  parameters  are   identical  to  the
  2036.      'file_open' function.
  2037.  
  2038.      This function  will close  the specified  file while saving its current
  2039.      mode, access type, and position.  The file is then reopened in  the new
  2040.      mode and  access type.  Use the 'file_reset' function to return it back
  2041.      to its previous state & position.
  2042.  
  2043.      The creation control parameter is ignored unless the file was  not open
  2044.      when this function is invoked.
  2045.  
  2046.      If the  FNOCREATE parameter is passed, then the file must exist on disk
  2047.      or the function will fail.  If the FCREATE parameter  is used  then the
  2048.      functions action  will be  based on  the 'rw' parameter.  The following
  2049.      actions are taken based on this parameter:
  2050.  
  2051.            FREAD    Open existing file, error if not present.
  2052.            FMODIFY  Open existing file, create if not present.
  2053.            FAPPEND  Open existing file, create if not present.
  2054.            FWRITE   Delete any existing file, create new file.
  2055.  
  2056.      It is suggested the files that are used  for read/write  or read/append
  2057.      access be  opened using  the FREAD parameter and that the 'file_change'
  2058.      and 'file_reset' functions be used when it comes  time to  write to it.
  2059.      This method will provide the proper interaction with SHARE.EXE and will
  2060.      avoid other BBS nodes from being denied access to the file.
  2061.  
  2062.      Also, when modifying sections of a record, the record should be re-read
  2063.      after the  'file_change' function  is called to guarantee the integrity
  2064.      of the file.
  2065.  
  2066.  
  2067.  
  2068.  
  2069.                                                                          44
  2070.  
  2071.      * Return Value
  2072.  
  2073.       0    is returned if function completed successfully.
  2074.      -1    is returned if an attempt made to create an existing file.
  2075.      -2    is returned if no file handles are available.  This  can be cured
  2076.            by changing the files parameter in the system CONFIG.SYS file.
  2077.      -3    is returned  if an  attempt is  made to open an existing file and
  2078.            the file cannot be found.
  2079.      -4    is returned if the file cannot  be successfully  opened in stream
  2080.            access mode.
  2081.      -5    is returned  if the  file is  share locked.   This return code is
  2082.            only returned after several attempts were made to  open the file.
  2083.            This usually  indicates that  either a program section is leaving
  2084.            the file set for writing too long or has failed to make  the call
  2085.            to 'file_reset'.
  2086.  
  2087.  
  2088.      * See Also
  2089.  
  2090.            file_open, file_close, file_reset
  2091.  
  2092.  
  2093.      * Example
  2094.  
  2095.        See example in file_reset for proper use of all file functions.
  2096.  
  2097.                                                                          45
  2098.  
  2099.      FILE_RESET
  2100.      ----------
  2101.  
  2102.      * Summary
  2103.  
  2104.      int file_reset(file);           /* Restore shared file access        */
  2105.      FS  *file;                      /* Pointer to file structure         */
  2106.  
  2107.  
  2108.      * Description
  2109.  
  2110.      This function  assumes that  a file  was already  open and the function
  2111.      'file_change' has been  called,  otherwise,  unpredictable  results may
  2112.      occur.
  2113.  
  2114.      This function  will close the specified file thus flushing all buffers.
  2115.      The file is then reopened back  in its  original access  mode, and then
  2116.      the file is repositioned to its original location.
  2117.  
  2118.      It is  suggested the  files that are used for read/write or read/append
  2119.      access be opened using the FREAD  parameter and  that the 'file_change'
  2120.      and 'file_reset'  functions be  used when it comes time to write to it.
  2121.      This method will provide the proper interaction with SHARE.EXE and will
  2122.      avoid other BBS nodes from being denied access to the file.
  2123.  
  2124.      Also when  modifying sections of a record, the record should be re-read
  2125.      after the 'file_change' function is called  to guarantee  the integrity
  2126.      of the file.
  2127.  
  2128.      Return values  are identical  to the  'file_open' function  since it is
  2129.      recalled to open the file back up in its previous mode.
  2130.  
  2131.  
  2132.      * Return Value
  2133.  
  2134.       0    is returned if function completed successfully.
  2135.      -1    is returned if an attempt made to create an existing file.
  2136.      -2    is returned if no file handles are available.  This  can be cured
  2137.            by changing the files parameter in the system CONFIG.SYS file.
  2138.      -3    is returned  if an  attempt is  made to open an existing file and
  2139.            the file cannot be found.
  2140.      -4    is returned if the file cannot  be successfully  opened in stream
  2141.            access mode.
  2142.      -5    is returned  if the  file is  share locked.   This return code is
  2143.            only returned after several attempts were made to  open the file.
  2144.            This usually  indicates that  either a program section is leaving
  2145.            the file set for writing too long or has failed to make  the call
  2146.            to 'file_reset'.
  2147.  
  2148.  
  2149.      * See Also
  2150.  
  2151.            file_close, file_change, file_open
  2152.  
  2153.  
  2154.  
  2155.  
  2156.                                                                          46
  2157.  
  2158.      * Example
  2159.  
  2160.  
  2161.      #include <string.h>
  2162.      #include <io.h>
  2163.      #include <stdio.h>
  2164.      #include "dmdata.h"
  2165.      #include "dmfunc.h"
  2166.      void show_error(int rtc);   /* print out file error messages.   */
  2167.      FS  rfile;                  /* file access structure            */
  2168.      int rtc;                    /* return code value                */
  2169.      char buffer[128];           /* record buffer                    */
  2170.  
  2171.      /*
  2172.       * Open the record file for reading in binary mode
  2173.       */
  2174.  
  2175.      strcpy(rfile.name, "GAME.REC");    /* setup filename      */
  2176.  
  2177.      if (rtc = file_open(&rfile, FREAD, FBINARY, FNOCREATE))
  2178.        show_error(rtc);
  2179.  
  2180.      /*
  2181.       * Now change access to modify access
  2182.       */
  2183.  
  2184.      if (rtc = file_change(&rfile, FMODIFY, FBINARY, FNOCREATE))
  2185.        show_error(rtc);
  2186.  
  2187.      /*
  2188.       * Now go to record 0 and read it in
  2189.       * to guarantee the record is current
  2190.       */
  2191.  
  2192.      lseek(rfile.fh, 0L, 0);   /* position at record 0   */
  2193.      read(rfile.fh, buff, 128);  /* read in 128 byte record  */
  2194.  
  2195.      /*
  2196.       * Update the record with the date
  2197.       */
  2198.  
  2199.      get_date(buff);     /* copy in current date   */
  2200.      write(rfile.fh, buff, 128); /* now write it back out  */
  2201.  
  2202.      /*
  2203.       * Now return to read mode
  2204.       */
  2205.  
  2206.      if (rtc = file_reset(rfile))
  2207.        show_error(rtc);
  2208.  
  2209.      file_close(rfile);
  2210.  
  2211.  
  2212.                                                                          47
  2213.  
  2214.      void show_error(rtc)
  2215.      {
  2216.        switch(rtc) {     /* process return code    */
  2217.          case 0:   /* all ok */
  2218.            return;
  2219.  
  2220.          case -1:  /* create error */
  2221.            report_error("Error - File already exists\r\n");
  2222.            exit(1);
  2223.  
  2224.          case -2:  /* no handles */
  2225.            report_error("Error - All file handles in use\r\n");
  2226.            exit(1);
  2227.  
  2228.          case -3:  /* file not found */
  2229.            report_error("Error - File not found\r\n");
  2230.            exit(1);
  2231.  
  2232.          case -4:  /* stream unavailable */
  2233.            report_error("Error - Stream access denied\r\n");
  2234.            exit(1);
  2235.  
  2236.          case -5:  /* file locked */
  2237.            report_error("Error - File is locked\r\n");
  2238.            exit(1);
  2239.  
  2240.          default:  /* unexpected return code */
  2241.            report_error("Error - Bad return code from file_open()\r\n");
  2242.            exit(1);
  2243.        }
  2244.      }
  2245.  
  2246.  
  2247.                                                                          48
  2248.  
  2249.      GET_DTA
  2250.      -------
  2251.  
  2252.      * Summary
  2253.  
  2254.      char *get_dta();                /* Get disk transfer address         */
  2255.  
  2256.  
  2257.      * Description
  2258.  
  2259.      This function  is used to return the DOS current disk transfer address.
  2260.      It is primarily used as an internal function  but it  is made available
  2261.      to you.
  2262.  
  2263.  
  2264.      * Return Value
  2265.  
  2266.      This function always returns 0.
  2267.  
  2268.  
  2269.      * Example
  2270.  
  2271.      #include "dmfunc.h"
  2272.      char *dta;            /* the transfer address    */
  2273.  
  2274.  
  2275.      /*
  2276.       * Get the DOS disk transfer address
  2277.       */
  2278.  
  2279.      dta = get_dta();
  2280.  
  2281.  
  2282.                                                                          49
  2283.  
  2284.      FSEARCH
  2285.      -------
  2286.  
  2287.      * Summary
  2288.  
  2289.      int fsearch(name, buffer);      /* Search disk for files             */
  2290.      char *name;                     /* Match name string pointer         */
  2291.      char *buffer;                   /* Buffer to store file list         */
  2292.  
  2293.  
  2294.      * Description
  2295.  
  2296.      This function  is equivalent  to doing  a DIR command in DOS.  The name
  2297.      parameter is the name  you  wish  to  search  against  and  may include
  2298.      standard wildcard characters.
  2299.  
  2300.      Buffer is  filled with a series of null terminated file names that have
  2301.      matched the name parameter.  Buffer should be  allocated to accommodate
  2302.      all matched file names.
  2303.  
  2304.  
  2305.      * Return Value
  2306.  
  2307.      0     if no files match.
  2308.            Otherwise returns the number of matches.
  2309.  
  2310.  
  2311.      * Example
  2312.  
  2313.      #include "dmfunc.h"
  2314.      int count;              /* number of matches            */
  2315.      int total;              /* number of matches            */
  2316.      char sname[80];         /* the match name to search on  */
  2317.      char buffer[2048];      /* large match buffer           */
  2318.      char *names;            /* filename pointer             */
  2319.  
  2320.      /*
  2321.       * Get all .DAT files
  2322.       */
  2323.  
  2324.      strcpy(sname, "*.DAT");  /* build search name   */
  2325.      count = fsearch(sname, buffer); /* now do the search     */
  2326.  
  2327.      /*
  2328.       * Report results
  2329.       */
  2330.  
  2331.      names = buffer;           /* name pointer       */
  2332.      total = count;            /* total matches      */
  2333.      print_string("\r\n");     /* new line           */
  2334.      while(count) {      /* do as long as we have names   */
  2335.        print_string(names);          /* print next filename      */
  2336.        names += strlen(names) + 1;   /* point to next name       */
  2337.        count--;                      /* one less to do           */
  2338.      }
  2339.      sprintf(sname,     "Total     file(s)     %d    found\r\n"),    total);
  2340.      print_string(sname);
  2341.  
  2342.  
  2343.                                                                          50
  2344.  
  2345.      FHIDE
  2346.      -----
  2347.  
  2348.      * Summary
  2349.  
  2350.      int fhide(name);                /* Hide the specified file           */
  2351.      char *name;                     /* Name of file to hide              */
  2352.  
  2353.  
  2354.      * Description
  2355.  
  2356.      This function  will set  the hide attribute bit  in the specified file.
  2357.      This function should not be formed on open files.
  2358.  
  2359.  
  2360.      * Return Value
  2361.  
  2362.      Undefined return value.
  2363.  
  2364.  
  2365.      * Example
  2366.  
  2367.      #include "dmfunc.h"
  2368.  
  2369.      /*
  2370.       * Hide the file
  2371.       */
  2372.  
  2373.      fhide("SECRET.DAT");                           /* hide the file         */
  2374.  
  2375.  
  2376.  
  2377.                                                                          51
  2378.  
  2379.      FUNHIDE
  2380.      -------
  2381.  
  2382.      * Summary
  2383.  
  2384.      int funhide(name);              /* UnHide the specified file         */
  2385.      char *name;                     /* Name of file to hide              */
  2386.  
  2387.  
  2388.      * Description
  2389.  
  2390.      This function will clear the hide attribute bit  in the specified file.
  2391.      This function should not be formed on open files.
  2392.  
  2393.  
  2394.      * Return Value
  2395.  
  2396.      Undefined return value.
  2397.  
  2398.  
  2399.      * Example
  2400.  
  2401.      #include "dmfunc.h"
  2402.  
  2403.      /*
  2404.       * UnHide the file
  2405.       */
  2406.  
  2407.      funhide("SECRET.DAT");                         /* unhide the file       */
  2408.  
  2409.  
  2410.  
  2411.                                                                          52
  2412.  
  2413.      BBS services
  2414.      ------------
  2415.  
  2416.      The BBS services provide a simple  means for  the programmer  to access
  2417.      all of the required BBS parameters without needing any knowledge of the
  2418.      BBS files.
  2419.  
  2420.      All file access is done using SHARE.EXE compatible file access so as to
  2421.      remain compatible in a multi-user environment.
  2422.  
  2423.      The following section will detail all the BBS functions in the library.
  2424.      Note that some of  these functions  may be  there as  support for other
  2425.      functions.
  2426.  
  2427.  
  2428.                                                                          53
  2429.  
  2430.      READ_BBS_INFO
  2431.      -------------
  2432.  
  2433.      * Summary
  2434.  
  2435.      int read_bbs_info(node, path, type);
  2436.      int node;                       /* BBS node number                   */
  2437.      char *path;                     /* Path where BBS files reside       */
  2438.      char *type;                     /* BBS type identifier               */
  2439.  
  2440.  
  2441.      * Description
  2442.  
  2443.      This function  is an overall  BBS access functions.   It may be used in
  2444.      liew of calling the other functions independantly.
  2445.  
  2446.      First,  this function  will attempt  to call  the remote  comm port  by
  2447.      making a call to IO_OPEN.  An error is returned if this function fails.
  2448.  
  2449.      Next,  it initializes the  C randon number generator by calling the  DM
  2450.      function RANDOM_CLOCK and then calling the C function SRAND.
  2451.  
  2452.      Next, the DM data structure bbs_path is set to contain the value passed
  2453.      in in the path parameter.
  2454.  
  2455.      Next, the type parameter  is scanned for  a recognizable  BBS type.  If
  2456.      a match is found then the appropriate bbs function is called.   See the
  2457.      descriptions of the individual functions to see what files each expects
  2458.      to find and read.
  2459.  
  2460.      The following list show the parameters for the path & type strings:
  2461.  
  2462.                path            type             function called
  2463.      ----------------------------------------------------------------------
  2464.        RBBS file path          NULL             BBS_READ (15.x)
  2465.        RBBS file path          RBBS             RBBS_READ (16.x)
  2466.        Quick BBS file path     QBBS             QBBS_READ
  2467.        PC-Board file path      PCBOARD          PCBBS_READ (12.1)
  2468.        PC-Board file path      PCBOARD14        PCBBS_READ (14.0)
  2469.        Wildcat file path       WILDCAT          WCBBS_READ
  2470.        GAP BBS file path       GAP              GBBS_READ
  2471.        NULL                    NULL             MON_READ
  2472.                                                 MON_USER
  2473.  
  2474.  
  2475.  
  2476.                                                                          54
  2477.  
  2478.      * Return Value
  2479.  
  2480.      Returns 0  if all ok
  2481.      ===== Comm Port Return Codes =====
  2482.      Returns -1 if can't find NODES.BBS file
  2483.      Returns -2 if can't read node record
  2484.      Returns -3 if can't identify comm port device
  2485.      ===== RBBS 15.x Return Codes =====
  2486.      Returns -11 if can't find MESSAGES file
  2487.      Returns -12 if can't read node record
  2488.      Returns -13 if can't find USERS files
  2489.      Returns -14 if can't read user record
  2490.      Returns -15 if can't find PASSWRDS file
  2491.      Returns -16 if can't read security level record
  2492.      ===== RBBS 16.x Return Codes =====
  2493.      Returns -21 if can't find MESSAGES file
  2494.      Returns -22 if can't read node record
  2495.      Returns -23 if can't find DORINFOx files
  2496.      Returns -24 if can't read user record
  2497.      ===== PC-Board Return Codes =====
  2498.      Returns -31 if can't find PCBOARD.SYS info
  2499.      Returns -32 if can't read PCBOARD.SYS info
  2500.      ===== Wildcat Return Codes =====
  2501.      Returns -41 if can't find CALLINFO.BBS info
  2502.      Returns -42 if can't read CALLINFO.BBS info
  2503.      ===== QBBS Return Codes =====
  2504.      Returns -51 if can't find DORINFOx.DEF info
  2505.      Returns -52 if can't read DORINFOx.DEF info
  2506.      ===== GAP Return Codes =====
  2507.      Returns -51 if can't find DOOR.SYS info
  2508.      Returns -52 if can't read DOOR.SYS info
  2509.      ===== WWIV Return Codes =====
  2510.      Returns -51 if can't find CHAIN.TXT info
  2511.      Returns -52 if can't read CHAIN.TXT info
  2512.      ===== Door Monitor Return Codes =====
  2513.      Returns -101 if can't find TIMEOFFx.DOR
  2514.      Returns -102 if can't find or read NAMES.DOR
  2515.      ===== Misc Return Codes =====
  2516.      Returns 1 if bad type parameter
  2517.  
  2518.  
  2519.  
  2520.                                                                          55
  2521.  
  2522.      * Example
  2523.  
  2524.      #include "dmfunc.h"
  2525.      int rtc;            /* return code value        */
  2526.      int node;           /* current node             */
  2527.  
  2528.      /*
  2529.       * Read in the BBS information
  2530.       */
  2531.  
  2532.      node = atoi(argv[1]);       /* get node number from cmd line  */
  2533.      rtc = read_bbs_info(node, argv[2], argv[3]);
  2534.      switch(rtc) {   /* process return code     */
  2535.        case  0:  /* all ok */
  2536.          break;
  2537.  
  2538.        case -1:  /* cant' locate NODES.BBS */
  2539.          report_error("Error - Can't locate NODES.BBS\r\n");
  2540.          exit(1);
  2541.  
  2542.        case -2: /* can't read node record */
  2543.          report_error("Error - Can't read node record in NODES.BBS\r\n");
  2544.          exit(1);
  2545.  
  2546.        case -3: /* can't identify device */
  2547.          report_error("Error - Invalid device in NODES.BBS\r\n");
  2548.          exit(1);
  2549.  
  2550.        case -11:/* can't find MESSAGES */
  2551.          report_error("Error - Can't locate MESSAGES\r\n");
  2552.          exit(1);
  2553.  
  2554.        case -12:/* can't read MESSAGES */
  2555.          report_error("Error - Can't read node record in MESSAGES\r\n");
  2556.          exit(1);
  2557.  
  2558.        case -13:/* can't locate USERS */
  2559.          report_error("Error - Can't locate USERS\r\n");
  2560.          exit(1);
  2561.  
  2562.        case -14:/* can't read USERS */
  2563.          report_error("Error - Can't read USERS\r\n");
  2564.          exit(1);
  2565.  
  2566.        case -15:/* can't locate PASSWRDS */
  2567.          report_error("Error - Can't locate PASSWRDS\r\n");
  2568.          exit(1);
  2569.  
  2570.        case -16:/* can't read PASSWRDS */
  2571.          report_error("Error - Can't read security record in PASSWRDS\r\n");
  2572.          exit(1);
  2573.  
  2574.  
  2575.                                                                          56
  2576.  
  2577.        case -21:/* can't find MESSAGES */
  2578.          report_error("Error - Can't locate MESSAGES\r\n");
  2579.          exit(1);
  2580.  
  2581.        case -22:/* can't read MESSAGES */
  2582.          report_error("Error - Can't read node record in MESSAGES\r\n");
  2583.          exit(1);
  2584.  
  2585.        case -23:/* can't locate DORINFOx.DEF */
  2586.          report_error("Error - Can't locate DORINFOx.DEF\r\n");
  2587.          exit(1);
  2588.  
  2589.        case -24:/* can't read DORINFOx.DEF */
  2590.          report_error("Error - Can't read DORINFOx.DEF\r\n");
  2591.          exit(1);
  2592.  
  2593.        case -31:/* can't find PCBOARD.SYS */
  2594.          report_error("Error - Can't locate PCBOARD.SYS\r\n");
  2595.          exit(1);
  2596.  
  2597.        case -32:/* can't read PCBOARD.SYS */
  2598.          report_error("Error - Can't read record in PCBOARD.SYS\r\n");
  2599.          exit(1);
  2600.  
  2601.        case -41:/* can't find CALLINFO.BBS */
  2602.          report_error("Error - Can't locate CALLINFO.BBS\r\n");
  2603.          exit(1);
  2604.  
  2605.        case -42:/* can't read CALLINFO.BBS */
  2606.          report_error("Error - Can't read record in CALLINFO.BBS\r\n");
  2607.          exit(1);
  2608.  
  2609.        case -51:/* can't find DORINFOx.DEF */
  2610.          report_error("Error - Can't locate DORINFOx.DEF\r\n");
  2611.          exit(1);
  2612.  
  2613.        case -52:/* can't read DORINFOx.DEF */
  2614.          report_error("Error - Can't read record in DORINFOx.DEF\r\n");
  2615.          exit(1);
  2616.  
  2617.        case -61:/* can't find DOOR.SYS */
  2618.          report_error("Error - Can't locate DOOR.SYS\r\n");
  2619.          exit(1);
  2620.  
  2621.        case -62:/* can't read DOOR.SYS */
  2622.          report_error("Error - Can't read record in DOOR.SYS\r\n");
  2623.          exit(1);
  2624.  
  2625.        case -71:/* can't find CHAIN.TXT */
  2626.          report_error("Error - Can't locate CHAIN.TXT\r\n");
  2627.          exit(1);
  2628.  
  2629.        case -72:/* can't read CHAIN.TXT */
  2630.          report_error("Error - Can't read record in CHAIN.TXT\r\n");
  2631.          exit(1);
  2632.  
  2633.        case -101:/* can't access TIMEOFFx.DOR */
  2634.          report_error("Error - Can't access TIMEOFFx.DOR\r\n");
  2635.          exit(1);
  2636.  
  2637.        case -102:/* can't access DORINFOx.DEF */
  2638.          report_error("Error - Can't access NAMES.DOR\r\n");
  2639.          exit(1);
  2640.  
  2641.        default: /* unexpected return code */
  2642.          report_error("Error - Undefined return code from read_bbs_info()\r\n");
  2643.          exit(1);
  2644.      }
  2645.  
  2646.      /*
  2647.       * At this point all is OK
  2648.       */
  2649.  
  2650.      print_string("Welcome, ");
  2651.      print_string(user_name);
  2652.      print_string(", to the game.\r\n");
  2653.  
  2654.  
  2655.                                                                          57
  2656.  
  2657.      BBS_READ
  2658.      --------
  2659.  
  2660.      * Summary
  2661.  
  2662.      int bbs_read(node);             /* Read in the RBBS information      */
  2663.      int node;                       /* RBBS node number                  */
  2664.  
  2665.  
  2666.      * Description
  2667.  
  2668.      This  function  will  read  in  all  RBBS  15.1A/15.1B  compatible data
  2669.      structures.  This function will also  work the  16.1x version,  but new
  2670.      functions will be added in the near future to take advantage of the BBS
  2671.      Door Information File generated by RBBS 16.
  2672.  
  2673.      All bbs files (MESSAGES, USERS, PASSWRDS) are assumed  to exist  in the
  2674.      subdirectory specified by the DM data structure 'bbs_dir'.
  2675.  
  2676.      First, the  MESSAGES file  is opened and the appropriate node record is
  2677.      read into the DM data structure 'bbs_node_info'.  An error  is returned
  2678.      if the  file cannot be located or if the node record is not found.  The
  2679.      users name and logon time  are  extracted  and  saved  in  the  DM data
  2680.      structures 'user_name' and 'user_signon'.
  2681.  
  2682.      Next, the  USERS file  is opened and searched for the current user.  An
  2683.      error is returned if the file cannot be located or if the  users record
  2684.      cannot be  found.  The users security level, graphics type, nulls flag,
  2685.      caps flag, and page length are  transferred to  the DM  data structures
  2686.      'user_security',   'user_graphics',   'user_nulls',   'user_caps',  and
  2687.      'user_page' respectively.  The DM data structure 'user_signon'  is then
  2688.      modified to  reflect the  amount of time the user has already used that
  2689.      day.
  2690.  
  2691.      Next, the PASSWRDS files is opened  and searched  for the corresponding
  2692.      entry that  matches the  users security level.  An error is returned if
  2693.      either the file cannot  be located  or there  is no  corresponding time
  2694.      entry that  matches the  users security  level.   The DM data structure
  2695.      'user_signoff' is then set to reflect the amount  of time  the user has
  2696.      remaining in connect time.
  2697.  
  2698.  
  2699.      * Return Value
  2700.  
  2701.       0    is returned if function completed successfully.
  2702.      -1    is returned if the MESSAGES file cannot be located.
  2703.      -2    is returned if the node record in MESSAGES cannot be read.
  2704.      -3    is returned if the USERS file cannot be located.
  2705.      -4    is returned if the current users record cannot be read.
  2706.      -5    is returned if the PASSWRDS file cannot be located.
  2707.      -6    is returned if the security level record cannot be read.
  2708.  
  2709.  
  2710.  
  2711.  
  2712.                                                                          58
  2713.  
  2714.      * Example
  2715.  
  2716.      #include "dmfunc.h"
  2717.      int rtc;            /* return code value        */
  2718.      int node;           /* current node             */
  2719.  
  2720.      /*
  2721.       * Read in the RBBS information
  2722.       */
  2723.  
  2724.      node = atoi(argv[1]);       /* get node number from cmd line  */
  2725.      strcpy(bbs_dir, argv[2]);   /* get bbs path from cmd line     */
  2726.      rtc = bbs_read(node);       /* read bbs information           */
  2727.      switch(rtc) {   /* process return code     */
  2728.        case  0:  /* all ok */
  2729.          break;
  2730.  
  2731.        case -1:  /* cant' locate MESSAGES */
  2732.          report_error("Error - Can't locate MESSAGES\r\n");
  2733.          exit(1);
  2734.  
  2735.        case -2: /* can't locate node record */
  2736.          report_error("Error - Can't locate node record in MESSAGES\r\n");
  2737.          exit(1);
  2738.  
  2739.        case -3: /* can't locate USERS */
  2740.          report_error("Error - Can't locate USERS\r\n");
  2741.          exit(1);
  2742.  
  2743.        case -4: /* can't find users record */
  2744.          report_error("Error - Can't locate user record\r\n");
  2745.          exit(1);
  2746.  
  2747.        case -5: /* can't locate PASSWRDS */
  2748.          report_error("Error - Can't locate PASSWRDS\r\n");
  2749.          exit(1);
  2750.  
  2751.        case -6: /* can't locate security level record */
  2752.          report_error("Error - Can't locate security record\r\n");
  2753.          exit(1);
  2754.  
  2755.        default: /* unexpected return code */
  2756.          report_error("Error - Unexpected return code from bbs_read()\r\n");
  2757.          exit(1);
  2758.      }
  2759.  
  2760.      /*
  2761.       * At this point all is OK
  2762.       */
  2763.  
  2764.      print_string("Welcome, ");
  2765.      print_string(user_name);
  2766.      print_string(", to the game.\r\n");
  2767.  
  2768.  
  2769.                                                                          59
  2770.  
  2771.      RBBS_READ
  2772.      ---------
  2773.  
  2774.      * Summary
  2775.  
  2776.      int rbbs_read(node);            /* Read in the RBBS information      */
  2777.      int node;                       /* RBBS node number                  */
  2778.  
  2779.  
  2780.      * Description
  2781.  
  2782.      This function will read in  all RBBS 16.1A compatible  data structures.
  2783.  
  2784.      All bbs  files (MESSAGES,  DORINFOx.DEF)  are assumed  to exist  in the
  2785.      subdirectory specified by the DM data structure 'bbs_dir'.
  2786.  
  2787.      First, the  MESSAGES file  is opened and the appropriate node record is
  2788.      read into the DM data structure 'bbs_node_info'.  An error  is returned
  2789.      if the  file cannot be located or if the node record is not found.  The
  2790.      users name and logon time  are  extracted  and  saved  in  the  DM data
  2791.      structures 'user_name' and 'user_signon'.
  2792.  
  2793.      Next,  DORINFOx.DEF is opened and read into a temporary data structure.
  2794.      An error is returned if the file cannot be located or if the file can't
  2795.      be read  to completion.  The users name,  security level,  and graphics
  2796.      type are extracted and  stored in appropriate data structures.   Values
  2797.      undefined  by these  files are  set to  default values  (see section on
  2798.      default data values).
  2799.  
  2800.  
  2801.      * Return Value
  2802.  
  2803.       0    is returned if function completed successfully.
  2804.      -1    is returned if the MESSAGES file cannot be located.
  2805.      -2    is returned if the node record in MESSAGES cannot be read.
  2806.      -3    is returned if the DORINFOx.DEF file cannot be located.
  2807.      -4    is returned if the DORINFOx.DEF cannot be read to completion.
  2808.  
  2809.  
  2810.  
  2811.  
  2812.                                                                          60
  2813.  
  2814.      * Example
  2815.  
  2816.      #include "dmfunc.h"
  2817.      int rtc;            /* return code value        */
  2818.      int node;           /* current node             */
  2819.  
  2820.      /*
  2821.       * Read in the RBBS information
  2822.       */
  2823.  
  2824.      node = atoi(argv[1]);       /* get node number from cmd line  */
  2825.      strcpy(bbs_dir, argv[2]);   /* get bbs path from cmd line     */
  2826.      rtc = rbbs_read(node);      /* read bbs information           */
  2827.      switch(rtc) {   /* process return code     */
  2828.        case  0:  /* all ok */
  2829.          break;
  2830.  
  2831.        case -1:  /* cant' locate MESSAGES */
  2832.          report_error("Error - Can't locate MESSAGES\r\n");
  2833.          exit(1);
  2834.  
  2835.        case -2: /* can't locate node record */
  2836.          report_error("Error - Can't locate node record in MESSAGES\r\n");
  2837.          exit(1);
  2838.  
  2839.        case -3: /* can't locate DORINFOx.DEF */
  2840.          report_error("Error - Can't locate DORINFOx.DEF\r\n");
  2841.          exit(1);
  2842.  
  2843.        case -4: /* can't read DORINFOx.DEF */
  2844.          report_error("Error - Can't read DORINFOx.DEF\r\n");
  2845.          exit(1);
  2846.  
  2847.        default: /* unexpected return code */
  2848.          report_error("Error - Unexpected return code from rbbs_read()\r\n");
  2849.          exit(1);
  2850.      }
  2851.  
  2852.      /*
  2853.       * At this point all is OK
  2854.       */
  2855.  
  2856.      print_string("Welcome, ");
  2857.      print_string(user_name);
  2858.      print_string(", to the game.\r\n");
  2859.  
  2860.  
  2861.                                                                          61
  2862.  
  2863.      QBBS_READ
  2864.      ---------
  2865.  
  2866.      * Summary
  2867.  
  2868.      int qbbs_read(node);            /* Read in the QBBS information      */
  2869.      int node;                       /* RBBS node number                  */
  2870.  
  2871.  
  2872.      * Description
  2873.  
  2874.      This function will read in  all RBBS 16.1A compatible  data structures.
  2875.  
  2876.      The  bbs  file DORINFOx.DEF  is assumed  to exist  in the  subdirectory
  2877.      specified by the DM data structure 'bbs_dir'.
  2878.  
  2879.      The DORINFOx.DEF  is opened  and read  into a temporary data structure.
  2880.      An error is returned if the file cannot be located or if the file can't
  2881.      be read  to completion.  The users name,  security level,  and graphics
  2882.      type are extracted and  stored in appropriate data structures.   Values
  2883.      undefined  by this  files are  set to  default values  (see  section on
  2884.      default data values).
  2885.  
  2886.  
  2887.      * Return Value
  2888.  
  2889.       0    is returned if function completed successfully.
  2890.      -1    is returned if the DORINFOx.DEF file cannot be located.
  2891.      -2    is returned if the DORINFOx.DEF cannot be read to completion.
  2892.  
  2893.  
  2894.  
  2895.  
  2896.                                                                          62
  2897.  
  2898.      * Example
  2899.  
  2900.      #include "dmfunc.h"
  2901.      int rtc;            /* return code value        */
  2902.      int node;           /* current node             */
  2903.  
  2904.      /*
  2905.       * Read in the RBBS information
  2906.       */
  2907.  
  2908.      node = atoi(argv[1]);       /* get node number from cmd line  */
  2909.      strcpy(bbs_dir, argv[2]);   /* get bbs path from cmd line     */
  2910.      rtc = qbbs_read(node);      /* read bbs information           */
  2911.      switch(rtc) {   /* process return code     */
  2912.        case  0:  /* all ok */
  2913.          break;
  2914.  
  2915.        case -1: /* can't locate DORINFOx.DEF */
  2916.          report_error("Error - Can't locate DORINFOx.DEF\r\n");
  2917.          exit(1);
  2918.  
  2919.        case -2: /* can't read DORINFOx.DEF */
  2920.          report_error("Error - Can't read DORINFOx.DEF\r\n");
  2921.          exit(1);
  2922.  
  2923.        default: /* unexpected return code */
  2924.          report_error("Error - Unexpected return code from qbbs_read()\r\n");
  2925.          exit(1);
  2926.      }
  2927.  
  2928.      /*
  2929.       * At this point all is OK
  2930.       */
  2931.  
  2932.      print_string("Welcome, ");
  2933.      print_string(user_name);
  2934.      print_string(", to the game.\r\n");
  2935.  
  2936.  
  2937.                                                                          63
  2938.  
  2939.      PCBBS_READ
  2940.      ----------
  2941.  
  2942.      * Summary
  2943.  
  2944.      int pcbbs_read(node);           /* Read in the PCB 12.1 information  */
  2945.      int node;                       /* BBS node number                   */
  2946.  
  2947.  
  2948.      * Description
  2949.  
  2950.      This function  will read  in the PCBOARD.SYS file and then transfer all
  2951.      related information into the  DM  data  structure  'bbs_node_info'. All
  2952.      user parameters  are copied  into the DM data structures beginning with
  2953.      'user_'.  See 'bbs_read' for details.
  2954.  
  2955.      The DM data structure 'pcbbs_data' is used to  hold the  incoming info,
  2956.      but is not used after that.
  2957.  
  2958.      The file PCBOARD.SYS is expected to reside in subdirectory specified by
  2959.      the DM data structure 'bbs_dir'.
  2960.  
  2961.  
  2962.      * Return Value
  2963.  
  2964.       0    is returned if function completed successfully.
  2965.      -1    is returned if the PCBOARD.SYS file cannot be located.
  2966.      -2    is returned if the PCBOARD.SYS file cannot be read.
  2967.  
  2968.  
  2969.  
  2970.  
  2971.                                                                          64
  2972.  
  2973.      * Example
  2974.  
  2975.      int pcbbs_read();     /* open & read PCBOARD.SYS    */
  2976.      int rtc;              /* return code value          */
  2977.      int node;             /* current node               */
  2978.  
  2979.  
  2980.      /*
  2981.       * Read in the PC-Board information
  2982.       */
  2983.  
  2984.      node = atoi(argv[1]);       /* get node number from cmd line  */
  2985.      strcpy(bbs_dir, argv[2]);   /* get bbs path from cmd line     */
  2986.  
  2987.      rtc = pcbbs_read(node);    /* read bbs information   */
  2988.  
  2989.      switch(rtc)     /* process return code     */
  2990.      {
  2991.        case 0: /* all ok */
  2992.          break;
  2993.  
  2994.        case -1: /* cant' locate PCBOARD.SYS */
  2995.          report_error("Error - Can't locate PCBOARD.SYS\r\n");
  2996.          exit(1);
  2997.  
  2998.        case -2: /* can't read PCBOARD.SYS */
  2999.          report_error("Error - Can't read PCBOARD.SYS\r\n");
  3000.          exit(1);
  3001.  
  3002.        default: /* unexpected return code */
  3003.          report_error("Error - Bad return code from pcbbs_read()\r\n");
  3004.          exit(1);
  3005.      }
  3006.  
  3007.      /*
  3008.       * At this point all is OK
  3009.       */
  3010.  
  3011.      print_string("Welcome, ");
  3012.      print_string(user_name);
  3013.      print_string(", to the game.\r\n");
  3014.  
  3015.  
  3016.                                                                          65
  3017.  
  3018.      PCBBS2_READ
  3019.      -----------
  3020.  
  3021.      * Summary
  3022.  
  3023.      int pcbbs2_read(node);          /* Read in the PCB 14.0 information  */
  3024.      int node;                       /* BBS node number                   */
  3025.  
  3026.  
  3027.      * Description
  3028.  
  3029.      This function  will read  in the PCBOARD.SYS file and then transfer all
  3030.      related information into the  DM  data  structure  'bbs_node_info'. All
  3031.      user parameters  are copied  into the DM data structures beginning with
  3032.      'user_'.  See 'bbs_read' for details.
  3033.  
  3034.      The DM data structure 'pcbbs2_data' is used to hold the  incoming info,
  3035.      but is not used after that.
  3036.  
  3037.      The file PCBOARD.SYS is expected to reside in subdirectory specified by
  3038.      the DM data structure 'bbs_dir'.
  3039.  
  3040.  
  3041.      * Return Value
  3042.  
  3043.       0    is returned if function completed successfully.
  3044.      -1    is returned if the PCBOARD.SYS file cannot be located.
  3045.      -2    is returned if the PCBOARD.SYS file cannot be read.
  3046.  
  3047.  
  3048.  
  3049.  
  3050.                                                                          66
  3051.  
  3052.      * Example
  3053.  
  3054.      int pcbbs2_read();    /* open & read PCBOARD.SYS    */
  3055.      int rtc;              /* return code value          */
  3056.      int node;             /* current node               */
  3057.  
  3058.  
  3059.      /*
  3060.       * Read in the PC-Board information
  3061.       */
  3062.  
  3063.      node = atoi(argv[1]);       /* get node number from cmd line  */
  3064.      strcpy(bbs_dir, argv[2]);   /* get bbs path from cmd line     */
  3065.  
  3066.      rtc = pcbbs2_read(node);    /* read bbs information   */
  3067.  
  3068.      switch(rtc)     /* process return code     */
  3069.      {
  3070.        case 0: /* all ok */
  3071.          break;
  3072.  
  3073.        case -1: /* cant' locate PCBOARD.SYS */
  3074.          report_error("Error - Can't locate PCBOARD.SYS\r\n");
  3075.          exit(1);
  3076.  
  3077.        case -2: /* can't read PCBOARD.SYS */
  3078.          report_error("Error - Can't read PCBOARD.SYS\r\n");
  3079.          exit(1);
  3080.  
  3081.        default: /* unexpected return code */
  3082.          report_error("Error - Bad return code from pcbbs_read()\r\n");
  3083.          exit(1);
  3084.      }
  3085.  
  3086.      /*
  3087.       * At this point all is OK
  3088.       */
  3089.  
  3090.      print_string("Welcome, ");
  3091.      print_string(user_name);
  3092.      print_string(", to the game.\r\n");
  3093.  
  3094.  
  3095.                                                                          67
  3096.  
  3097.      WCBBS_READ
  3098.      ----------
  3099.  
  3100.      * Summary
  3101.  
  3102.      int wcbbs_read(node);           /* Read in the Wildcat information   */
  3103.      int node;                       /* BBS node number                   */
  3104.  
  3105.  
  3106.      * Description
  3107.  
  3108.      This function  will read in the CALLINFO.BBS file and then transfer all
  3109.      related information into the  DM  data  structure  'bbs_node_info'. All
  3110.      user parameters  are copied  into the DM data structures beginning with
  3111.      'user_'.  See 'bbs_read' for details.
  3112.  
  3113.      The DM data structure 'wcbbs_data' is used to  hold the  incoming info,
  3114.      but is not used after that.
  3115.  
  3116.      The file CALLINFO.BBS  is expected to reside in  subdirectory specified
  3117.      by the DM data structure 'bbs_dir'.
  3118.  
  3119.  
  3120.      * Return Value
  3121.  
  3122.       0    is returned if function completed successfully.
  3123.      -1    is returned if the CALLINFO.BBS file cannot be located.
  3124.      -2    is returned if the CALLINFO.BBS file cannot be read.
  3125.  
  3126.  
  3127.  
  3128.  
  3129.                                                                          68
  3130.  
  3131.      * Example
  3132.  
  3133.      int wcbbs_read();     /* open & read CALLINFO.BBS   */
  3134.      int rtc;              /* return code value          */
  3135.      int node;             /* current node               */
  3136.  
  3137.  
  3138.      /*
  3139.       * Read in the Wildcat BBS information
  3140.       */
  3141.  
  3142.      node = atoi(argv[1]);       /* get node number from cmd line  */
  3143.      strcpy(bbs_dir, argv[2]);   /* get bbs path from cmd line     */
  3144.  
  3145.      rtc = wcbbs_read(node);   /* read bbs information   */
  3146.  
  3147.      switch(rtc)     /* process return code     */
  3148.      {
  3149.        case 0: /* all ok */
  3150.          break;
  3151.  
  3152.        case -1: /* cant' locate CALLINFO.BBS */
  3153.          report_error("Error - Can't locate CALLINFO.BBS\r\n");
  3154.          exit(1);
  3155.  
  3156.        case -2: /* can't read CALLINFO.BBS */
  3157.          report_error("Error - Can't read CALLINFO.BBS\r\n");
  3158.          exit(1);
  3159.  
  3160.        default: /* unexpected return code */
  3161.          report_error("Error - Bad return code from wcbbs_read()\r\n");
  3162.          exit(1);
  3163.      }
  3164.  
  3165.      /*
  3166.       * At this point all is OK
  3167.       */
  3168.  
  3169.      print_string("Welcome, ");
  3170.      print_string(user_name);
  3171.      print_string(", to the game.\r\n");
  3172.  
  3173.  
  3174.                                                                          69
  3175.  
  3176.      GBBS_READ
  3177.      ---------
  3178.  
  3179.      * Summary
  3180.  
  3181.      int gbbs_read(node);            /* Read in the GAP BBS information   */
  3182.      int node;                       /* BBS node number                   */
  3183.  
  3184.  
  3185.      * Description
  3186.  
  3187.      This function  will read  in the  DOOR.SYS file  and then  transfer all
  3188.      related information into the  DM  data  structure  'bbs_node_info'. All
  3189.      user parameters  are copied  into the DM data structures beginning with
  3190.      'user_'.  See 'bbs_read' for details.
  3191.  
  3192.      The DM data structure  'gbbs_data' is used to  hold the  incoming info,
  3193.      but is not used after that.
  3194.  
  3195.      The file DOOR.SYS  is expected to reside  in subdirectory  specified by
  3196.      by the DM data structure 'bbs_dir'.
  3197.  
  3198.  
  3199.      * Return Value
  3200.  
  3201.       0    is returned if function completed successfully.
  3202.      -1    is returned if the DOOR.SYS file cannot be located.
  3203.      -2    is returned if the DOOR.SYS file cannot be read.
  3204.  
  3205.  
  3206.  
  3207.  
  3208.                                                                          70
  3209.  
  3210.      * Example
  3211.  
  3212.      int gbbs_read();      /* open & read DOOR.SYS       */
  3213.      int rtc;              /* return code value          */
  3214.      int node;             /* current node               */
  3215.  
  3216.  
  3217.      /*
  3218.       * Read in the GAP BBS information
  3219.       */
  3220.  
  3221.      node = atoi(argv[1]);       /* get node number from cmd line  */
  3222.      strcpy(bbs_dir, argv[2]);   /* get bbs path from cmd line     */
  3223.  
  3224.      rtc = gbbs_read(node);      /* read bbs information   */
  3225.  
  3226.      switch(rtc)     /* process return code     */
  3227.      {
  3228.        case 0: /* all ok */
  3229.          break;
  3230.  
  3231.        case -1: /* cant' locate DOOR.SYS */
  3232.          report_error("Error - Can't locate DOOR.SYS\r\n");
  3233.          exit(1);
  3234.  
  3235.        case -2: /* can't read DOOR.SYS */
  3236.          report_error("Error - Can't read DOOR.SYS\r\n");
  3237.          exit(1);
  3238.  
  3239.        default: /* unexpected return code */
  3240.          report_error("Error - Bad return code from gbbs_read()\r\n");
  3241.          exit(1);
  3242.      }
  3243.  
  3244.      /*
  3245.       * At this point all is OK
  3246.       */
  3247.  
  3248.      print_string("Welcome, ");
  3249.      print_string(user_name);
  3250.      print_string(", to the game.\r\n");
  3251.  
  3252.  
  3253.                                                                          71
  3254.  
  3255.      WBBS_READ
  3256.      ---------
  3257.  
  3258.      * Summary
  3259.  
  3260.      int wbbs_read(node);            /* Read in the WWIV BBS information  */
  3261.      int node;                       /* BBS node number                   */
  3262.  
  3263.  
  3264.      * Description
  3265.  
  3266.      This function  will read  in the CHAIN.TXT file  and then  transfer all
  3267.      related information into the  DM  data  structure  'bbs_node_info'. All
  3268.      user parameters  are copied  into the DM data structures beginning with
  3269.      'user_'.  See 'bbs_read' for details.
  3270.  
  3271.      The DM data structure  'ascii_data' is used to  hold the incoming info,
  3272.      but is not used after that.
  3273.  
  3274.      The file CHAIN.TXT is expected to reside  in subdirectory  specified by
  3275.      by the DM data structure 'bbs_dir'.
  3276.  
  3277.  
  3278.      * Return Value
  3279.  
  3280.       0    is returned if function completed successfully.
  3281.      -1    is returned if the CHAIN.TXT file cannot be located.
  3282.      -2    is returned if the CHAIN.TXT file cannot be read.
  3283.  
  3284.  
  3285.  
  3286.  
  3287.                                                                          72
  3288.  
  3289.      * Example
  3290.  
  3291.      int wbbs_read();      /* open & read CHAIN.TXT      */
  3292.      int rtc;              /* return code value          */
  3293.      int node;             /* current node               */
  3294.  
  3295.  
  3296.      /*
  3297.       * Read in the GAP BBS information
  3298.       */
  3299.  
  3300.      node = atoi(argv[1]);       /* get node number from cmd line  */
  3301.      strcpy(bbs_dir, argv[2]);   /* get bbs path from cmd line     */
  3302.  
  3303.      rtc = wbbs_read(node);      /* read bbs information   */
  3304.  
  3305.      switch(rtc)     /* process return code     */
  3306.      {
  3307.        case 0: /* all ok */
  3308.          break;
  3309.  
  3310.        case -1: /* cant' locate DOOR.SYS */
  3311.          report_error("Error - Can't locate CHAIN.TXT\r\n");
  3312.          exit(1);
  3313.  
  3314.        case -2: /* can't read DOOR.SYS */
  3315.          report_error("Error - Can't read CHAIN.TXT\r\n");
  3316.          exit(1);
  3317.  
  3318.        default: /* unexpected return code */
  3319.          report_error("Error - Bad return code from gbbs_read()\r\n");
  3320.          exit(1);
  3321.      }
  3322.  
  3323.      /*
  3324.       * At this point all is OK
  3325.       */
  3326.  
  3327.      print_string("Welcome, ");
  3328.      print_string(user_name);
  3329.      print_string(", to the game.\r\n");
  3330.  
  3331.  
  3332.                                                                          73
  3333.  
  3334.      PAGE_OPERATOR
  3335.      -------------
  3336.  
  3337.      * Summary
  3338.  
  3339.      int page_operator();            /* Page the SysOp                    */
  3340.  
  3341.  
  3342.      * Description
  3343.  
  3344.      This function will allow the user to page  the SysOp.   If  the DM data
  3345.      structure  'remote_user'  is  0,  then  the  function will return a 'no
  3346.      answer' response.
  3347.  
  3348.      The    DM    data     structures     'bbs_time_info.sysop_start'    and
  3349.      'bbs_time_info.sysop_stop' are  checked to identify the SysOp's working
  3350.      hours.
  3351.  
  3352.      If the  DM data  structure 'bbs_node_info.sysop_avail'  is set  to ' 1'
  3353.      then a  test is  made to  verify that the current time falls within the
  3354.      SysOp's working hours.  If the 'bbs_node_info.sysop_annoy' is  set to '
  3355.      1' then the page is also allowed.
  3356.  
  3357.      If the  page is  allowed then  the local  bell will be rung 10 times in
  3358.      order to attempt to reach the SysOp.  If the SysOp wishes to answer the
  3359.      page,  he/she  presses  the  ESC  button  on the local keyboard and the
  3360.      message "SysOp in, go ahead..." will be printed to the virtual console.
  3361.  
  3362.  
  3363.      * Return Value
  3364.  
  3365.      0     is returned if there is no answer to the page  or if  the page is
  3366.            not currently permitted.
  3367.      1     is returned if the SysOp answered the page.
  3368.  
  3369.  
  3370.  
  3371.  
  3372.                                                                          74
  3373.  
  3374.      * Example
  3375.  
  3376.      #include "dmfunc.h"
  3377.      int rtc;                /* return code value        */
  3378.      char buffer[80];        /* command buffer           */
  3379.  
  3380.      /*
  3381.       * Get next user command.
  3382.       */
  3383.  
  3384.      io_linput(buffer);    /* get a command string    */
  3385.      if (strcmp(buffer, "~NO_CARRIER") == 0) {
  3386.        /* Loss of carrier */
  3387.  
  3388.        local_print("Error - Loss of carrier\r\n");
  3389.        exit(1);
  3390.      } else
  3391.        if (strcmp(buffer, "~NOT_ACTIVE") == 0) {
  3392.          /* Loss of carrier */
  3393.  
  3394.          local_print("Error - No activity for 5 minutes\r\n");
  3395.          exit(1);
  3396.        } else
  3397.          if (strcmp(buffer, "~TIME_WARNING") == 0) {
  3398.            /* Loss of carrier */
  3399.  
  3400.            local_print("Warning -  Less than  5 minutes connect time\r\n");
  3401.            exit(1);
  3402.          } else
  3403.            if (strcmp(buffer, "~TIMEOUT") == 0) {
  3404.              /* Loss of carrier */
  3405.  
  3406.              local_print("Error - All connect time has been used\r\n");
  3407.              exit(1);
  3408.            } else
  3409.              if (strcmp(strupr(buffer), "PAGE") == 0) {
  3410.                /* Page the operator */
  3411.  
  3412.                rtc = page_operator();    /* attempt to page the SysOp   */
  3413.                if (rtc)
  3414.                  chat_mode();      /* chat with user    */
  3415.                else
  3416.                  print_string("Sorry, the SysOp is not available.\r\n");
  3417.              } else {
  3418.                /* ... process other user commands ... */
  3419.      }
  3420.  
  3421.  
  3422.                                                                          75
  3423.  
  3424.      CHAT_MODE
  3425.      ---------
  3426.  
  3427.      * Summary
  3428.  
  3429.      int chat_mode();                /* Enter CHAT mode                   */
  3430.  
  3431.  
  3432.      * Description
  3433.  
  3434.      This function  will allow  the SySop  to initiate  CHAT mode.   In this
  3435.      mode, characters  entered from  the virtual  console are echoed back to
  3436.      it.  CHAT mode  continues until  an ESC  character is  entered from the
  3437.      local console.
  3438.  
  3439.      The 'chat_mode'  function does  not test  for end-of-line condition and
  3440.      therefore the SysOp and remote user will need to use  the ENTER  key to
  3441.      go to the next line as word wrap is not supported.
  3442.  
  3443.  
  3444.      * Return Value
  3445.  
  3446.      This function always returns a 0.
  3447.  
  3448.  
  3449.      * Example
  3450.  
  3451.        See example under page_operator for proper use of chat_mode.
  3452.  
  3453.                                                                          76
  3454.  
  3455.      Door Monitor services
  3456.      ---------------------
  3457.  
  3458.      The  door  monitor  services  provide  a  simple  to  access all of the
  3459.      required door monitor parameters without needing  any knowledge  of the
  3460.      door monitor files.  It also provides a means of returning the time and
  3461.      score information to the door monitor.
  3462.  
  3463.      These functions are compatible with both  the Bob  Wescott Door Monitor
  3464.      and the GMon Door Monitor.
  3465.  
  3466.      All file access is done using SHARE.EXE compatible file access so as to
  3467.      remain compatible in a multi-user environment.
  3468.  
  3469.      The following section will detail all the door monitor functions in the
  3470.      library.  Note that some of these functions may be there as support for
  3471.      other functions.
  3472.  
  3473.  
  3474.  
  3475.                                                                          77
  3476.  
  3477.      MON_READ
  3478.      --------
  3479.  
  3480.      * Summary
  3481.  
  3482.      int mon_read(node);             /* Read in the monitor info          */
  3483.      int node;                       /* RBBS node number                  */
  3484.  
  3485.  
  3486.      * Description
  3487.  
  3488.      This function will read in the file 'TIMEOFFx.DOR' which is expected to
  3489.      reside the  current DOS  directory.  The 'x' represents the node number
  3490.      and is compatible with both of  the  door  monitors.    All appropriate
  3491.      information is  stored in the DM data structures beginning with 'mon_'.
  3492.      Next, all of the DM data structures beginning  with 'user_'  are filled
  3493.      in from this information.
  3494.  
  3495.      Note that  no node information is available from the door monitor.  You
  3496.      will therefore need to  set the  following DM  data structures  to some
  3497.      default value:
  3498.  
  3499.      bbs_node_info.snoop
  3500.            ' 0' = no echo to local display
  3501.            ' 1' = echo to local display
  3502.      bbs_node_info.sysop_avail
  3503.            ' 0' = disallow paging
  3504.            ' 1' = allow paging during sysop hours
  3505.      bbs_node_info.sysop_annoy
  3506.            ' 0' = normal paging (check hours)
  3507.            ' 1' = always allow paging
  3508.  
  3509.  
  3510.      * Return Value
  3511.  
  3512.      0     is returned if the monitor is not active.
  3513.      1     is returned  if the  files were successfully read and the monitor
  3514.            has been flagged active (DM data structure 'mon_active' is set to
  3515.            1
  3516.  
  3517.  
  3518.  
  3519.  
  3520.                                                                          78
  3521.  
  3522.      * Example
  3523.  
  3524.      #include "dmfunc.h"
  3525.      int rtc;              /* return code value        */
  3526.      int node;             /* current node             */
  3527.  
  3528.  
  3529.      /*
  3530.       * Read in the door monitor information
  3531.       */
  3532.  
  3533.      node = atoi(argv[1]);   /* get node number from cmd line  */
  3534.      if (mon_read(node)) {   /* read mon information           */
  3535.        if (mon_player(user_name, mon_user)) {
  3536.         report_error("Error - Can't locate NAMES.DOR\r\n");
  3537.         exit(1);
  3538.        }
  3539.      } else {
  3540.        report_error("Error - Can't locate TIMEOFFx.DOR\r\n");
  3541.        exit(1);
  3542.      }
  3543.  
  3544.      /*
  3545.       *  Set NODE info to defaults
  3546.       */
  3547.  
  3548.      bbs_node_info.snoop[0] = ' '; /* allow snoop    */
  3549.      bbs_node_info.snoop[1] = '1';
  3550.      bbs_node_info.sysop_avail[0] = ' ';
  3551.      bbs_node_info.sysop_avail[1] = '0';/* no paging      */
  3552.      bbs_node_info.sysop_annoy[0] = ' ';
  3553.      bbs_node_info.sysop_annoy[1] = '0';
  3554.  
  3555.  
  3556.      /*
  3557.       * At this point all is OK
  3558.       */
  3559.  
  3560.      print_string("Welcome, ");
  3561.      print_string(user_name);
  3562.      print_string(", to the game.\r\n");
  3563.  
  3564.  
  3565.                                                                          79
  3566.  
  3567.      MON_WRITE
  3568.      ---------
  3569.  
  3570.      * Summary
  3571.  
  3572.      int mon_write(node, points);    /* Write out the monitor info        */
  3573.      int node;                       /* RBBS node number                  */
  3574.      int points;                     /* Points to add to monitor score    */
  3575.  
  3576.  
  3577.      * Description
  3578.  
  3579.      This  function  will  write  out  the  file 'POINTSx.DOR' which will be
  3580.      created  in  the  subdirectory  specified  by  the  DM  data  structure
  3581.      'mon_dir'  (which  is  filled  in  by the 'mon_read' function.  The 'x'
  3582.      represents the node number and is  compatible  with  both  of  the door
  3583.      monitors.   This file  is used  to return the time the game was exited,
  3584.      and the number of points to add to the door  monitor score  as a result
  3585.      of having  used your  door.   This point value is arbitrary and you may
  3586.      decide on whatever value you feel is fair.
  3587.  
  3588.      This function returns with  no action  taken if  the DM  data structure
  3589.      'mon_active' is 0 indicating that the monitor is not in use.
  3590.  
  3591.  
  3592.      * Return Value
  3593.  
  3594.      This function always returns 0.
  3595.  
  3596.  
  3597.      * Example
  3598.  
  3599.      #include "dmfunc.h"
  3600.      int node;             /* current node                   */
  3601.      int score;            /* today score                    */
  3602.      int node_save;        /* node saved from command line   */
  3603.      int old_score;        /* previous days score            */
  3604.      int new_score;        /* score as result of today       */
  3605.  
  3606.  
  3607.      /*
  3608.       * Write out timeoff and today score
  3609.       * if the monitor was active.
  3610.       */
  3611.  
  3612.      node  = node_save;                /* get node number from back  */
  3613.      score = new_score - old_score;    /* award user difference      */
  3614.      mon_write(node, score);           /* write mon information      */
  3615.      mon_exit(node);                   /* exit via monitor if active */
  3616.      exit(0);                          /* else exit normally    */
  3617.  
  3618.  
  3619.                                                                          80
  3620.  
  3621.      MON_PLAYER
  3622.      ----------
  3623.  
  3624.      * Summary
  3625.  
  3626.      int mon_player(name, user);     /* Read in the player info           */
  3627.      char *name;                     /* Place to store name               */
  3628.      int user;                       /* Monitor user #                    */
  3629.  
  3630.  
  3631.      * Description
  3632.  
  3633.      This function  will read  in the  file 'NAMES.DOR' which is expected to
  3634.      reside in the directory  specified by  the DM  data structure 'mon_dir'
  3635.      (which is  filled in  by the  function 'mon_read').   The users name is
  3636.      extracted and stored in the string pointed to by the 'name' parameter.
  3637.  
  3638.      Note that door monitor  user number  (stored in  the DM  data structure
  3639.      'mon_user') is read in by the function 'mon_read'.
  3640.  
  3641.  
  3642.      * Return Value
  3643.  
  3644.      0 is  returned if the function completed successfully. 1 is returned if
  3645.      the file  NAMES.DOR cannot  be located  or read.  2 is  returned if the
  3646.      monitor is not active.
  3647.  
  3648.  
  3649.      * Example
  3650.  
  3651.        See mon_read for example of how to use mon_player.
  3652.  
  3653.  
  3654.                                                                          81
  3655.  
  3656.      MON_EXIT
  3657.      --------
  3658.  
  3659.      * Summary
  3660.  
  3661.      int mon_exit(node);             /* Exit back to door monitor         */
  3662.      int node;                       /* RBBS node number                  */
  3663.  
  3664.  
  3665.      * Description
  3666.  
  3667.      This  function  will  exit  back  to the door monitor provided the door
  3668.      monitor is active.  The door  monitor  is  expected  to  reside  in the
  3669.      directory specified  by the DM data structure 'mon_dir' which is filled
  3670.      in by 'mon_read'.
  3671.  
  3672.      This function returns with  no action  taken if  the DM  data structure
  3673.      'mon_active' is 0 indicating that the monitor is not in use.
  3674.  
  3675.  
  3676.      * Return Value
  3677.  
  3678.      This function always returns 0.
  3679.  
  3680.  
  3681.      * Example
  3682.  
  3683.      #include "dmfunc.h"
  3684.      int node;             /* current node                 */
  3685.      int score;            /* today score                  */
  3686.      int node_save;        /* node saved from command line */
  3687.      int old_score;        /* previous days score          */
  3688.      int new_score;        /* score as result of today     */
  3689.  
  3690.      /*
  3691.       * Write out timeoff and today score
  3692.       * if the monitor was active.
  3693.       */
  3694.  
  3695.      node  = node_save;                /* get node number from back  */
  3696.      score = new_score - old_score;   /* award user difference */
  3697.  
  3698.      mon_write(node, score);   /* write mon information  */
  3699.      mon_exit(node);           /* exit via monitor if active */
  3700.      exit(0);                  /* else exit normally    */
  3701.  
  3702.  
  3703.                                                                          82
  3704.  
  3705.      Time services
  3706.      -------------
  3707.  
  3708.      The time monitor services provide a simple to access a set of functions
  3709.      related to time and to functions for controlling the amount of time the
  3710.      user may have in the program being run.
  3711.  
  3712.      The time controls  apply to the time  of day and to  the users security
  3713.      level.   The program TIMEGEN.EXE is  supplied with this library and may
  3714.      be distributed freely along with amy software you write.   This program
  3715.      will convert  a text file  into a time  control data file.   The sample
  3716.      file  TIME.DEF is  also supplied  with the  libraries and  may also  be
  3717.      distributed at no charge.
  3718.  
  3719.                                                                          83
  3720.  
  3721.      SLEEP
  3722.      -----
  3723.  
  3724.      * Summary
  3725.  
  3726.      int sleep(count);               /* Sleep for count seconds           */
  3727.      int count;                      /* Number of seconds to sleep        */
  3728.  
  3729.  
  3730.      * Description
  3731.  
  3732.      This  function will  pause the program  for a period  approximating the
  3733.      count value passed in.  It is not the ultimate in accuracy, but for the
  3734.      most part will be acurate to plus or minu .5 seconds.
  3735.  
  3736.  
  3737.      * Return Value
  3738.  
  3739.      This function always returns 0.
  3740.  
  3741.  
  3742.      * Example
  3743.  
  3744.      #include "dmfunc.h"
  3745.  
  3746.      /*
  3747.       * Wait after printing a message
  3748.       */
  3749.  
  3750.      print_string("Please wait..."); /* Print the wait message            */
  3751.      sleep(5);                       /* Delay                             */
  3752.      backup(14);                     /* Erase the message                 */
  3753.  
  3754.  
  3755.                                                                          84
  3756.  
  3757.      GET_DATE
  3758.      --------
  3759.  
  3760.      * Summary
  3761.  
  3762.      int get_date(dtstring);         /* Return current date               */
  3763.      char dtstring[12];              /* String to hold date               */
  3764.  
  3765.  
  3766.      * Description
  3767.  
  3768.      This function will return the date in Mon DD YYYY format where both the
  3769.      day and year values are  number string characters,  and the month value
  3770.      will be one of the following:   Jan, Feb, Mar, Apr, May, Jun, Jul, Aug,
  3771.      Sep, Oct, Nov, or Dec.
  3772.  
  3773.  
  3774.      * Return Value
  3775.  
  3776.      This function always returns 0.
  3777.  
  3778.  
  3779.      * Example
  3780.  
  3781.      #include "dmfunc.h"
  3782.      char dtstring[12];              /* String to receive date            */
  3783.  
  3784.      /*
  3785.       * Get and show current date
  3786.       */
  3787.  
  3788.      get_date(dtstring);             /* Get the date                      */
  3789.      print_string("Todays date: ");  /* Now display it                    */
  3790.      print_string(dtstring);
  3791.  
  3792.  
  3793.                                                                          85
  3794.  
  3795.      CVT_DAYS
  3796.      --------
  3797.  
  3798.      * Summary
  3799.  
  3800.      long cvt_days(dtstring);        /* Return current date as numeric    */
  3801.      char dtstring[12];              /* String to hold date               */
  3802.  
  3803.  
  3804.      * Description
  3805.  
  3806.      This function will convert  the date string passed in into  "the number
  3807.      of days since  Jan 01 0000.   It is not  totally accurate  in that leap
  3808.      years are not taken into account, but works satisfactorally for testing
  3809.      how long it has been since a user was last on.
  3810.  
  3811.  
  3812.      * Return Value
  3813.  
  3814.      This function always returns the converted value as a long
  3815.  
  3816.  
  3817.      * Example
  3818.  
  3819.      #include "dmfunc.h"
  3820.      long cvt_days();                /* Return numeric date value         */
  3821.      char msg[32];                   /* Work string                       */
  3822.      char ldstring[12];              /* Date last time on                 */
  3823.      char dtstring[12];              /* String to receive date            */
  3824.      long ltemp, ltem1;              /* Work variables                    */
  3825.  
  3826.      /*
  3827.       * Show how long since last on
  3828.       */
  3829.  
  3830.      get_date(dtstring);             /* Get the date                      */
  3831.      ltemp  = cvt_days(ldstring);    /* Compute last access date          */
  3832.      ltemp1 = cvt_days(dtstring);    /* Compute todays date               */
  3833.      sprintf(msg, "It has been %ld days since last time on.",
  3834.              ltemp1 - ltemp);
  3835.      print_string(msg);
  3836.  
  3837.  
  3838.                                                                          86
  3839.  
  3840.      CUR_TIME
  3841.      --------
  3842.  
  3843.      * Summary
  3844.  
  3845.      long cur_time(tmstring);        /* Return current time               */
  3846.  
  3847.  
  3848.      * Description
  3849.  
  3850.      This function will return the time as a long.   The time is returned as
  3851.      the number of seconds past midnight.
  3852.  
  3853.  
  3854.      * Return Value
  3855.  
  3856.      Returns the number of seconds past midnight.
  3857.  
  3858.  
  3859.      * Example
  3860.  
  3861.      #include "dmfunc.h"
  3862.      long cur_time();                /* Time function                     */
  3863.      long time_val;                  /* The time itself                   */
  3864.      char msg[80];                   /* Work buffer                       */
  3865.  
  3866.      /*
  3867.       * Get and show current time
  3868.       */
  3869.  
  3870.      time_val = cur_time();                  /* Get the time                      */
  3871.      sprintf(msg, "It is now %ld seconds after Midnight.\r\n");
  3872.      print_string(msg);
  3873.  
  3874.  
  3875.                                                                          87
  3876.  
  3877.      CVT_TIME
  3878.      --------
  3879.  
  3880.      * Summary
  3881.  
  3882.      long cvt_time(tmstring);        /* Return time as secs past Midnight */
  3883.      char tmstring[9];               /* String to hold time               */
  3884.  
  3885.  
  3886.      * Description
  3887.  
  3888.      This function will convert  the time string passed in into the function
  3889.      into the number of seconds past midnight. This value will be as acurate
  3890.      as your system clock.  The time is returned as a long.
  3891.  
  3892.  
  3893.      * Return Value
  3894.  
  3895.      This function returns the converted string as a long
  3896.  
  3897.  
  3898.      * Example
  3899.  
  3900.      #include "dmfunc.h"
  3901.      long cvt_days();                /* Return numeric date value         */
  3902.      char msg[32];                   /* Work string                       */
  3903.      char tmstring[12];              /* String to receive time            */
  3904.      long ltemp;                     /* Work variable                     */
  3905.  
  3906.      /*
  3907.       * Show how long after 12 midnight
  3908.       */
  3909.  
  3910.      get_time(tmstring);             /* Get the time                      */
  3911.      ltemp  = cvt_time(tmstring);    /* Compute the current value as secs */
  3912.      sprintf(msg, "It is now %ld seconds after Midnight.", ltemp);
  3913.      print_string(msg);
  3914.  
  3915.  
  3916.                                                                          88
  3917.  
  3918.      TEST_TIMEOUT
  3919.      ------------
  3920.  
  3921.      * Summary
  3922.  
  3923.      int test_timeout();             /* Test for time errors              */
  3924.  
  3925.  
  3926.      * Description
  3927.  
  3928.      This  function will  test for  two sepecific  timeout conditions.   The
  3929.      first condition is a time warning  and indicates that the user has less
  3930.      than  five minutes of  time remaining.   The time warning  will only be
  3931.      issued once.   The second  condition is a  time error.   This indicates
  3932.      that the  user has  used all  of the  time available  to him  for  this
  3933.      program.
  3934.  
  3935.      The  timeout conditions are  computed by comparing  the current time to
  3936.      that of  the time count  stored in  user_signoff.   It is important  to
  3937.      realize that if the user_signoff value  must always be greater than the
  3938.      user_signon  data structure.   This may be  guaranteed by  checking and
  3939.      adding the  number of seconds  in a day to  user_signoff if it is  less
  3940.      than user_signon.   This guarantees to avoid problems if the user is on
  3941.      while time  wraps past midnight.   All  BBS and  Door Monitor functions
  3942.      make this adjustment to user_signoff when it is initially set.
  3943.  
  3944.      This function is automatically called by both io_tests() and io_input()
  3945.      and the appropriate values are passed back to the caller.
  3946.  
  3947.  
  3948.      * Return Value
  3949.  
  3950.      0      is returned if there is no timeout condition.
  3951.      -1     is returned if there is a time warning condition.
  3952.      -2     is returned if there is a time error condition.
  3953.  
  3954.  
  3955.      * Example
  3956.  
  3957.      #include "dmfunc.h"
  3958.  
  3959.      /*
  3960.       * Test if time problems
  3961.       */
  3962.  
  3963.      st = time_warning();            /* Test for time problems            */
  3964.      if(st == -2)                    /* Time error condition              */
  3965.      {
  3966.        print_string("Error - you have used all of your connect time!/007");
  3967.        sleep(3);
  3968.        exit(1);
  3969.      }
  3970.      if(st == -1)                    /* Time warning condition            */
  3971.      {
  3972.        print_string("Warning, less than 5 mintutes remaining...\007");
  3973.        sleep(3);
  3974.        backup(42);
  3975.      }
  3976.  
  3977.  
  3978.                                                                          89
  3979.  
  3980.      TIME_CONTROLS
  3981.      -------------
  3982.  
  3983.      * Summary
  3984.  
  3985.      int time_controls(filename);    /* Test for time errors              */
  3986.      char *filename;                 /* Name of time definition file      */
  3987.  
  3988.  
  3989.      * Description
  3990.  
  3991.      This function will attempt to open the specified time control file.  If
  3992.      the file cannot be found,  then the bbs_time_info  sysop structures are
  3993.      set to the entire 24 hour hour period and  the user_access_level is set
  3994.      to -1.
  3995.  
  3996.      If the file is found, then its contents are read into the bbs_time_info
  3997.      data structure.   Next the structure is  search to see if it will allow
  3998.      access to this user based on his security stored in the  data structure
  3999.      user_security.   An error is returned if he has too low a level.  If he
  4000.      has  sufficient  sucurity,  then his  user_access_level  is set  to the
  4001.      highest value based on the contenets of user_security.   Next, the time
  4002.      tables are searched to find the  corresponding entry  in the time table
  4003.      to use.   This is based on  the data structure  user_start which should
  4004.      have been set to  the current time when the  BBS files were read.   The
  4005.      user_signoff is  then adjusted if  the time limit indicated in the time
  4006.      tables indicates that user_signoff is too high.
  4007.  
  4008.  
  4009.      * Return Value
  4010.  
  4011.      1      is returned if the time definition file is read and the user
  4012.             is found to have sufficient security to access the system.
  4013.      0      is returned if the time definition file cannot be found.
  4014.      -1     is returned if there is an error reading the time definition
  4015.             file.
  4016.      -2     is returned if the user has insufficient security to access
  4017.             the system.
  4018.      -3     is returned if the user has insufficient security to access
  4019.             the system during this time window.
  4020.  
  4021.  
  4022.                                                                          90
  4023.  
  4024.      * Example
  4025.  
  4026.      #include "dmfunc.h"
  4027.      int  st;                        /* Work variable                     */
  4028.  
  4029.      /*
  4030.       * Open time controls and test for lack of security
  4031.       */
  4032.  
  4033.      st = time_controls("GAME.TIM"); /* Test for time problems            */
  4034.      switch(st)                      /* Dispatch based on return code     */
  4035.      {
  4036.        case -3: /* Insufficient security for time window */
  4037.                 print_string("Error - Insufficient security at this time.");
  4038.                 print_string("\r\n");
  4039.                 print_string("        Try again later./r/n");
  4040.                 sleep(3);
  4041.                 exit(1);
  4042.                 break;
  4043.  
  4044.        case -2: /* Insufficient security */
  4045.                 print_string("Error - Insufficient security!\r\n");
  4046.                 print_string("        Check with SysOp./r/n");
  4047.                 sleep(3);
  4048.                 exit(1);
  4049.                 break;
  4050.  
  4051.        case -1: /* Bad read of file */
  4052.                 report_error("Error - Reading time definitions");
  4053.                 sleep(3);
  4054.                 break;
  4055.  
  4056.        case 0:  /* File is not being used */
  4057.                 break;
  4058.  
  4059.        case 1:  /* All is OK */
  4060.                 break;
  4061.      }
  4062.  
  4063.  
  4064.                                                                          91
  4065.  
  4066.      DAILY_CONTROLS
  4067.      --------------
  4068.  
  4069.      * Summary
  4070.  
  4071.      int daily_controls();           /* Test daily conditions             */
  4072.  
  4073.  
  4074.      * Description
  4075.  
  4076.      This function will test for daily controls based on the settings in the
  4077.      time definition file.  The time_controls function must be called first.
  4078.      If the user_access_level is set to -1 (indicating no time controls file
  4079.      was found), then the function will simply return.
  4080.  
  4081.      If the file was found, then a series of test are performed to determine
  4082.      if the  user  should  be allowed  access.   First the  contents  of the
  4083.      user_game_date  data structure are  compared to the current date to see
  4084.      if the user has been on during this day.   If they are different,  then
  4085.      the  current date is  copied into  user_game_date,  and the contents of
  4086.      user_day_time and user_day_games are cleared,  and the function returns
  4087.      with no error.
  4088.  
  4089.      If the  two dates match indicating  he has already been on  during this
  4090.      day,  the a test is  made to see if  the user is  required to be  off a
  4091.      particular  amount of  time  before reentering  the program.   The data
  4092.      structure user_game_end should  contain the last time  the user exitied
  4093.      the  program today.   This value is stored as  'number of seconds after
  4094.      midnight'.   The current time is  checked to see if  he has waited long
  4095.      enough and an error is returned if not.
  4096.  
  4097.      If there is no wait period or if the user has waited long enough,  then
  4098.      the time  definition values  are checked  to see  if there is a maximum
  4099.      number of  times that a  user of  his  user_access_level  may enter the
  4100.      program each day.  The data structure user_day_games should contain the
  4101.      number of times the user has been on that day.  An error is returned if
  4102.      the user has been on too many times.
  4103.  
  4104.      If there  is no daily game limit  or if  the user has  not exceeded it,
  4105.      then a check is made to see if the user has exceeded the maximum number
  4106.      of minutes he is allowed on each day.  The data structure user_day_time
  4107.      should contain the number of minutes the user has been on that day.  It
  4108.      is compared to  the maximum allowed in the tables for the  users access
  4109.      level, and if he has exceeded the limit an error is returned.
  4110.  
  4111.      If there is  no daily limit,  then the  function returns without error.
  4112.      If there is a daily limit,  and the user has not exceeded it,  then the
  4113.      amount of  time remaining  in the day is computed  and the value of the
  4114.      data structure user_signoff is modified as required.
  4115.  
  4116.  
  4117.      * Return Value
  4118.  
  4119.      0      is returned if there are no error conditions.
  4120.      -1     is returned if the user has not waited the required amount of
  4121.             time between accesses.
  4122.      -2     is returned if the user has exceeded the maximum times that he
  4123.             may enter the program each day.
  4124.      -3     is returned if the user has exceeded the maximum number of time
  4125.             he may acces the program each day.
  4126.  
  4127.  
  4128.                                                                          92
  4129.  
  4130.      * Example
  4131.  
  4132.      #include "dmfunc.h"
  4133.      int  st;                        /* Work variable                     */
  4134.  
  4135.      /*
  4136.       * Open time controls and test for lack of security
  4137.       */
  4138.  
  4139.      st = time_controls("GAME.TIM"); /* Test for time problems            */
  4140.      switch(st)                      /* Dispatch based on return code     */
  4141.      {
  4142.        case -3: /* Insufficient security for time window */
  4143.                 print_string("Error - Insufficient security at this time.");
  4144.                 print_string("\r\n");
  4145.                 print_string("        Try again later./r/n");
  4146.                 sleep(3);
  4147.                 exit(1);
  4148.                 break;
  4149.  
  4150.        case -2: /* Insufficient security */
  4151.                 print_string("Error - Insufficient security!\r\n");
  4152.                 print_string("        Check with SysOp./r/n");
  4153.                 sleep(3);
  4154.                 exit(1);
  4155.                 break;
  4156.  
  4157.        case -1: /* Bad read of file */
  4158.                 report_error("Error - Reading time definitions");
  4159.                 sleep(3);
  4160.                 break;
  4161.  
  4162.        case 0:  /* File is not being used */
  4163.                 break;
  4164.  
  4165.        case 1:  /* All is OK */
  4166.                 break;
  4167.      }
  4168.  
  4169.  
  4170.                                                                          93
  4171.      /*
  4172.       * Test daily controls
  4173.       */
  4174.  
  4175.      st = daily_controls();          /* Test for time problems            */
  4176.      switch(st)                      /* Dispatch based on return code     */
  4177.      {
  4178.        case -3: /* Exceeded daily time limit */
  4179.                 print_string("Error - You have you all of your daily time.");
  4180.                 print_string("\r\n");
  4181.                 print_string("        Try again tomorrow./r/n");
  4182.                 sleep(3);
  4183.                 exit(1);
  4184.                 break;
  4185.  
  4186.        case -2: /* Exceeded daily entry limit */
  4187.                 print_string("Error - Daily run limit exceeded!\r\n");
  4188.                 print_string("        Try again tomorrow./r/n");
  4189.                 sleep(3);
  4190.                 exit(1);
  4191.                 break;
  4192.  
  4193.        case -1: /* Isufficient wait */
  4194.                 report_error("Error - You must wait longer before you can");
  4195.                 print_string("\r\n");
  4196.                 print_string("        enter program, try later./r/n");
  4197.                 sleep(3);
  4198.                 exit(1);
  4199.                 break;
  4200.  
  4201.        case 0:  /* All is OK */
  4202.                 break;
  4203.      }
  4204.                 .
  4205.                 .
  4206.                 .
  4207.      /*
  4208.       * Finished for the day
  4209.       */
  4210.  
  4211.       user_day_games++;
  4212.       user_game_end  = cur_time();
  4213.       user_day_time += cur_time - user_start;
  4214.  
  4215.  
  4216.                                                                          94
  4217.  
  4218.      Time Control File Format
  4219.      ------------------------
  4220.  
  4221.      This section show the format  of the time control file  and explain the
  4222.      various fields.   The format  of this file along with  the descriptions
  4223.      and the program TIMEGEN.EXE may be distributed with your application.
  4224.  
  4225.      The  time definition  file is  an ASCII  file used  to create  the time
  4226.      control data file.  It has the following format:
  4227.  
  4228.      :SYSOP 1000 2330                                 ; Sysops hours
  4229.      :LEVEL  006  007 008 008 008 008 008 008         ; Level access classes
  4230.      :DAYT   000  000 000 000 000 000 000 000         ; Daily time limits
  4231.      :DAYG   001  002 003 003 003 003 003 003         ; Daily game limits
  4232.      :WAIT   000  030 030 000 000 000 000 000         ; Time between games
  4233.      :TIME  0000  060 060 060 060 060 060 060 120     ; Per game access
  4234.      :TIME  0600  000 030 030 030 030 030 030 030     ; Per game access
  4235.                                  .
  4236.                                  .
  4237.                                  .
  4238.      :TIME  2000  000 045 045 045 045 045 045 060     ; Per game access
  4239.  
  4240.      The first entry defines the SysOp hours.  This controls when the player
  4241.      may use  the page command.   These entires are expressed as HHMM.   The
  4242.      second entry may be smaller than the first.  As an example ":SYSOP 0700
  4243.      1900" allows the player to use the page command from 7am until 7pm. The
  4244.      entry  ":SYSOP 2200 0200" allows  the page command  to be used  between
  4245.      10pm and 2am.
  4246.  
  4247.      The  ":LEVEL"  entry defines  how different  security level  users have
  4248.      access to  the game.   This  line consists  of  8 entries  in ascending
  4249.      order.  Each entry corresponds to a game control level.   As an example
  4250.      let us consider the following entry:
  4251.  
  4252.                 ":LEVEL 010 020 030 040 050 060 070 080".
  4253.  
  4254.      Any user with a security level of less than 10 would not have access to
  4255.      the game.   Users with security level  10 through 19 would have level 0
  4256.      privelidges.   Users with security level 20 through 29 would have level
  4257.      1 privelidges, etc.  Priveledges are explained below.
  4258.  
  4259.      The  ":DAYT" entry defines the maximum time  in minutes each privelidge
  4260.      level may play the game per day.   This entry consists of 8 values each
  4261.      corresponding to a privelidge level in ascending order.   Each value is
  4262.      in  minutes.   A value of  0 represents  no daily  time limit  for that
  4263.      particular privelidge level.
  4264.  
  4265.  
  4266.                                                                          95
  4267.  
  4268.      The  ":DAYG"  entry defines  the maximum number  of times  the user may
  4269.      enter  the  game  on  a given day.   It consists  of 8 values  each one
  4270.      corresponds to  a privelidge level  in ascending order.   A value  of 0
  4271.      represents no game limit for that particular privelidge level.
  4272.  
  4273.      The ":WAIT" entry defines the amount  of time in minutes each user must
  4274.      wait between entering the game.   This entry consists  of 8 values each
  4275.      corresponding to a privelidge level in ascending order.
  4276.  
  4277.      The  ":TIME"  entries define  the amount  of time each  user may  spend
  4278.      during a single play session.   It consists of 9 values.   The first is
  4279.      the time  of day the period starts.   The remaining 8 are the game time
  4280.      limits for each of the 8 privelidge levels. Time limits are in minutes.
  4281.      A 0 value here means  that the user  may not play  the game during that
  4282.      time period. Each ":TIME" entry must be in ascending time of day order.
  4283.      There may be a maximum of 8 ":TIME" entries.
  4284.  
  4285.  
  4286.                                                                          96
  4287.  
  4288.      Running TIMEGEN.EXE
  4289.      -------------------
  4290.  
  4291.      This  section  explains  how to run  the  time control  file generation
  4292.      program.   The program takes the ASCII time control definition file and
  4293.      outputs a binary file  for use by the TIME_CONTROLS  and DAILY_CONTROLS
  4294.      functions.
  4295.  
  4296.      To build the time control file, the following command line is used:
  4297.  
  4298.                          TIMEGEN def_file time_file
  4299.  
  4300.      Where  def_file  is  the  ASCII  file defining  all  time controls  and
  4301.      time_file is  the output file that  the application  will read.   As an
  4302.      example,  to provide time controls for the MSTRMIND sample program, the
  4303.      following command line would be used:
  4304.  
  4305.                          TIMEGEN times.def mstrmind.tim
  4306.  
  4307.  
  4308.  
  4309.                                                                          97
  4310.  
  4311.      Data Structures
  4312.      ---------------
  4313.  
  4314.      This section will deal with  the data structures used by the DM library
  4315.      functions.   These fall into  three major catagories:  file access data
  4316.      structures, BBS access data structures, and user data structures.
  4317.  
  4318.      For the most part,  many of the BBS access structures are  only used by
  4319.      the DM library  as temporary locations to read in  the BBS information.
  4320.      The information is then transfered  to the user data structures.   Only
  4321.      the data structures relevant to the operation  of the library functions
  4322.      will be described in detail.
  4323.  
  4324.  
  4325.                                                                          98
  4326.  
  4327.      File Access Structures
  4328.      ----------------------
  4329.  
  4330.      This section will deal with those structures used the accedd the shared
  4331.      file functions provided in the library.  The following is an example of
  4332.      the file access structure and the associated defined values used to
  4333.      access the library functions:
  4334.  
  4335.      /*
  4336.       *
  4337.       * File Access Structures
  4338.       *
  4339.       */
  4340.  
  4341.      struct fs                               /* FILE ACCESS INFORMATION   */
  4342.      {
  4343.        char name[80];                        /* filename                  */
  4344.        int  fh;                              /* file handle               */
  4345.        FILE *fd;                             /* file descriptor           */
  4346.        int  open_flag;                       /* open flag                 */
  4347.        int  binary;                          /* open in binary mode       */
  4348.        int  hold_flag;                       /* previous open flag        */
  4349.        int  hold_mode;                       /* previous text/binary      */
  4350.        long hold_pos;                        /* previous position         */
  4351.      };
  4352.  
  4353.      The name field bust be filled in by the application program.  It should
  4354.      under  normal circumstances  not contain  any wilcard characters.   The
  4355.      file handle and  file descritor fields  are filled in  by the FILE_OPEN
  4356.      and  FILE_CHANGE and  FILE_RESET functions.   They be referenced at any
  4357.      time the file is open to  perform shared file I/O using the appropriate
  4358.      field for  either stream or  direct file access.   Microsoft recommends
  4359.      that most shared access be limited to direct file access.
  4360.  
  4361.      The remaining fields are used to store information relevant to the file
  4362.      between calls  to the file access functions.   These fields are for use
  4363.      by the library functions.
  4364.  
  4365.  
  4366.      /*
  4367.       *
  4368.       * File Access Definitions
  4369.       *
  4370.       */
  4371.  
  4372.      #define FS struct  fs
  4373.  
  4374.      #define FREAD      0
  4375.      #define FMODIFY    1
  4376.      #define FAPPEND    2
  4377.      #define FWRITE     3
  4378.      #define FTEXT      0
  4379.      #define FBINARY    1
  4380.      #define FNOCREATE  0
  4381.      #define FCREATE    1
  4382.  
  4383.      These definitions provide  a way of using defined values  as parameters
  4384.      to the library functions.  There meaning is apparent.
  4385.  
  4386.  
  4387.                                                                          99
  4388.  
  4389.      BBS Access Structures
  4390.      ---------------------
  4391.  
  4392.      This  section will  deal with  those structures used to access  the BBS
  4393.      files and to control node configuration during application runs.   Most
  4394.      of these structures  are only used temporarily in order  to read in the
  4395.      BBS configuration information  and then their information  is copied to
  4396.      the user data structures.
  4397.  
  4398.      The  following examples show  the various data structures.   A few also
  4399.      contain descriptions about  the structures where it is relevant  to the
  4400.      application or the running of the library.
  4401.  
  4402.      /*
  4403.       *
  4404.       * RBBS Node structures
  4405.       *
  4406.       */
  4407.  
  4408.      struct bbs_node                         /* NODE INFORMATION          */
  4409.      {
  4410.        char name[31];                        /* Last users name           */
  4411.        char sysop_avail[2];                  /* SysOp available flag      */
  4412.        char sysop_annoy[2];                  /* SysOp annoy flag          */
  4413.        char sysop_next[2];                   /* SysOp next on system flag */
  4414.        char line_printer[2];                 /* Line printer avail flag   */
  4415.        char doors_avail[2];                  /* DOORS available flag      */
  4416.        char eight_bits[2];                   /* Eight bit transmit flag   */
  4417.        char baud_rate[2];                    /* Baud rate                 */
  4418.        char upper_case[2];                   /* Upper case only flag      */
  4419.        char reserve_1[5];                    /* Reserved                  */
  4420.        char graphics_type[2];                /* Graphics type flag        */
  4421.        char sysop[2];                        /* User is SysOp flag        */
  4422.        char active[1];                       /* Activity flag             */
  4423.        char snoop[2];                        /* Snoop indicator           */
  4424.        char baud_dial[2];                    /* Dialed in baud rate       */
  4425.        char reserved_2[2];                   /* Reserved                  */
  4426.        char login_time[6];                   /* Time logged onto system   */
  4427.        char reserved_3[2];                   /* Reserved                  */
  4428.        char private_door[2];                 /* Access to private DOOR    */
  4429.        char transfer[2];                     /* Transfer function         */
  4430.        char daily_exit_date[10];             /* Last daily exit date      */
  4431.        char daily_exit_time[5];              /* Last daily exit time      */
  4432.        char reliable[2];                     /* Reliable mode             */
  4433.        char reserved_4[36];                  /* Reserved                  */
  4434.      };
  4435.  
  4436.  
  4437.                                                                          96
  4438.  
  4439.      The  bbs_node structure  contains all of  the configuration information
  4440.      for the BBS  under which the application is running.   Although this is
  4441.      an RBBS structure,  it applies to  all library functions as information
  4442.      pertaining to other BBS nodes is copied into this structure.
  4443.  
  4444.      Three  fields are  of interest here.   The sysop_avail  and sysop_annoy
  4445.      fields control whether or not the PAGE_OPERATOR function will allow the
  4446.      user to page the local operator.   The local function keys supported by
  4447.      LOCAL_INPUT will effect the contents of these two fields.
  4448.  
  4449.      The third field of interest  is the snoop field  which controls whether
  4450.      or not the output is echoed  to the local display.   The functions keys
  4451.      relating to snoop in LOCAL_INPUT will modify the contents of this field
  4452.      value.
  4453.  
  4454.  
  4455.      struct bbs_options                      /* USER OPTION INFORMATION   */
  4456.      {
  4457.        int  logins;                          /* Times logged on           */
  4458.        int  last_msg;                        /* Last message read         */
  4459.        char protocol[1];                     /* Transfer protocol         */
  4460.        char graphics[1];                     /* Graphics mode             */
  4461.        int  margins;                         /* Margin size               */
  4462.        int  bit_flags;                       /* Access options            */
  4463.        int  subscription;                    /* Date subscription started */
  4464.        char page_length;                     /* Page length (binary)      */
  4465.        char reserved[1];                     /* Reserved                  */
  4466.      };
  4467.  
  4468.      /*
  4469.       *
  4470.       * RBBS Node option definitions
  4471.       *
  4472.       */
  4473.  
  4474.      #define BBS_OPTION_BIT_15       0x8000
  4475.      #define BBS_OPTION_BIT_14       0x4000
  4476.      #define BBS_OPTION_BIT_13       0x2000
  4477.      #define BBS_OPTION_BIT_12       0x1000
  4478.      #define BBS_OPTION_BIT_11       0x0800
  4479.      #define BBS_OPTION_BIT_10       0x0400
  4480.      #define BBS_OPTION_BIT_9        0x0200
  4481.      #define BBS_OPTION_QUESTIONARE  0x0100
  4482.      #define BBS_OPTION_AUTODOWN     0x0080
  4483.      #define BBS_OPTION_FILES        0x0040
  4484.      #define BBS_OPTION_BULLETINS    0x0020
  4485.      #define BBS_OPTION_LF           0x0010
  4486.      #define BBS_OPTION_CASE         0x0008
  4487.      #define BBS_OPTION_NULLS        0x0004
  4488.      #define BBS_OPTION_EXPERT       0x0002
  4489.      #define BBS_OPTION_BELL         0x0001
  4490.  
  4491.  
  4492.  
  4493.                                                                          97
  4494.  
  4495.      /*
  4496.       *
  4497.       * RBBS User structure
  4498.       *
  4499.       */
  4500.  
  4501.      struct bbs_user                         /* USER INFORMATION          */
  4502.      {
  4503.        char name[31];                        /* Users name                */
  4504.        char password[15];                    /* Users password            */
  4505.        int  security;                        /* Security level            */
  4506.        struct bbs_options options;           /* User options              */
  4507.        char residence[24];                   /* City and state            */
  4508.        char reserved[19];                    /* Reserved                  */
  4509.        char last_on[14];                     /* Date & time last on       */
  4510.        char last_dir[3];                     /* Date last listed directory*/
  4511.        int  downloads;                       /* Total downloads           */
  4512.        int  uploads;                         /* Total uploads             */
  4513.        int  elapsed;                         /* Elapsed time user was on  */
  4514.      };
  4515.  
  4516.  
  4517.      /*
  4518.       *
  4519.       * RBBS 16.x DORINFOx.DEF file format
  4520.       *
  4521.       */
  4522.  
  4523.      /* Line  1 --> Name of RBBS system                                   */
  4524.      /* Line  2 --> SysOps first name                                     */
  4525.      /* Line  3 --> SysOps last name                                      */
  4526.      /* Line  4 --> Comm port name                                        */
  4527.      /* Line  5 --> Comm port parameters                                  */
  4528.      /* Line  6 --> Network type                                          */
  4529.      /* Line  7 --> Users first name                                      */
  4530.      /* Line  8 --> Users last name                                       */
  4531.      /* Line  9 --> Users city/state                                      */
  4532.      /* Line 10 --> Graphics                                              */
  4533.      /* Line 11 --> Security level                                        */
  4534.      /* Line 12 --> Time remaining in minutes                             */
  4535.  
  4536.  
  4537.                                                                          98
  4538.  
  4539.      /*
  4540.       *
  4541.       * PC-Board 12.1 BBS control structure
  4542.       *
  4543.       */
  4544.  
  4545.      struct pcbbs_data                       /* PC-BOARD BBS INFORMATION  */
  4546.      {
  4547.        char display[2];                      /* Display On/Off (-1/0)     */
  4548.        char printer[2];                      /* Printer On/Off (-1/0)     */
  4549.        char page_bell[2];                    /* Page Bell On/Off (-1/0)   */
  4550.        char caller_alarm[2];                 /* Caller Alarm On/Off (-1/0)*/
  4551.        char sysop_next[2];                   /* Sysop Next-On Flag        */
  4552.        char bps[4];                          /* CONNECT bps rate of caller*/
  4553.        char name[27];                        /* Name of caller plus 2 spcs*/
  4554.        char first[15];                       /* Callers first name padded */
  4555.        char graphics[2];                     /* Graphics Mode (-1/0)      */
  4556.        char password[12];                    /* Password of caller        */
  4557.        int  user_index;                      /* User's Record # in DBase  */
  4558.        long connect_time;                    /* Time logged on in seconds */
  4559.        long max_time;                        /* Allowed time in seconds   */
  4560.        long door_time;                       /* Time Exited to DOOR in sec*/
  4561.        char logon[5];                        /* Time logged on (hh:mm)    */
  4562.        int  conference;                      /* Confer. exited to DOS from*/
  4563.        int  conf_flags;                      /* Conf. 1-9 "joined flags"  */
  4564.        int  conf_time;                       /* Conference Time Add       */
  4565.        char dload_limit[8];                  /* Daily Download Byte Limit */
  4566.        int  uload_credit;                    /* Upload time credit        */
  4567.        char language[4];                     /* Language beging used      */
  4568.        char ecr_modem[2];                    /* Error Corr. Modem (-1/0)  */
  4569.        char chat;                            /* Last Node CHAT Flag Status*/
  4570.      };
  4571.  
  4572.  
  4573.                                                                          99
  4574.  
  4575.      /*
  4576.       *
  4577.       * PC-Board 14.0 BBS control structure
  4578.       *
  4579.       */
  4580.  
  4581.      struct  pcbbs2_data                     /* PC-BOARD 14.0 INFORMATION */
  4582.      {
  4583.        char display[2];                      /* Display On/Off (-1/0)     */
  4584.        char printer[2];                      /* Printer On/Off (-1/0)     */
  4585.        char page_bell[2];                    /* Page Bell On/Off (-1/0)   */
  4586.        char caller_alarm[2];                 /* Caller Alarm On/Off (-1/0)*/
  4587.        char sysop_next;                      /* Sysop Next-On Flag        */
  4588.        char ecr_modem[2];                    /* Error Corr. Modem (-1/0)  */
  4589.        char graphics;                        /* Graphics Mode (1/0)       */
  4590.        char chat;                            /* Last Node CHAT Flag Status*/
  4591.        char bps_open[5];                     /* OPEN bps rate of caller   */
  4592.        char bps[5];                          /* CONNECT bps rate of caller*/
  4593.        int  user_index;                      /* User's Record # in DBase  */
  4594.        char first[15];                       /* Callers first name padded */
  4595.        char password[12];                    /* Password of caller        */
  4596.        int  connect_time;                    /* Time logged on in minutes */
  4597.        char logon[5];                        /* Time logged on (hh:mm)    */
  4598.        int  max_time;                        /* Daily time limit in mins  */
  4599.        int  dload_limit;                     /* Daily Download Byte Limit */
  4600.        char conference;                      /* Confer. exited to DOS from*/
  4601.        char conf_flags[5];                   /* Conf. 1-9 "joined flags"  */
  4602.        char conf_scans[5];                   /* Conf. 1-9 "scanned flags" */
  4603.        int  conf_time;                       /* Conference Time Add       */
  4604.        int  uload_credit;                    /* Upload time credit        */
  4605.        char language[4];                     /* Language beging used      */
  4606.        char name[25];                        /* Name of caller plus 2 spcs*/
  4607.        int  time_left;                       /* Session time remaining    */
  4608.        char node;                            /* Node id                   */
  4609.        char event_time[5];                   /* Next event time           */
  4610.        char event_flag[2];                   /* Event active flag         */
  4611.        char event_move[2];                   /* Delay event till logoff?  */
  4612.        long msg_memory;                      /* Memorized message number  */
  4613.        char comm_port;                       /* Comm port number          */
  4614.        char reserved[4];                     /* Reserved for future use   */
  4615.      };
  4616.  
  4617.      These structure contains  the information passed to the door by PCBOARD
  4618.      via the PCBOARD.SYS file.  This information is examined and then copied
  4619.      into the bbs_node structure and the appropriate user structures.
  4620.  
  4621.  
  4622.                                                                         100
  4623.      /*
  4624.       *
  4625.       * Wildcat BBS CALLINFO.BBS file format
  4626.       *
  4627.       */
  4628.  
  4629.      /* Line  1 --> User name                                             */
  4630.      /* Line  2 --> baud rate 0=2400,1=300,2=1200,3=9600                  */
  4631.      /* Line  3 --> User city and state                                   */
  4632.      /* Line  4 --> User Access level                                     */
  4633.      /* Line  5 --> Logon time left in minutes                            */
  4634.      /* Line  6 --> Either COLOR or MONO user setting                     */
  4635.      /* Line  7 --> User password                                         */
  4636.      /* Line  8 --> User Record number                                    */
  4637.      /* Line  9 --> Total minutes on bbs                                  */
  4638.      /* Line 10 --> Time entered door hh:mm                               */
  4639.      /* Line 11 --> Time called bbs hh:mm                                 */
  4640.      /* Line 12 --> User confernces join                                  */
  4641.      /* Line 13 --> User daily d/l total                                  */
  4642.      /* Line 14 --> User max d/l per day                                  */
  4643.      /* Line 15 --> User daily d/l no of bytes in k                       */
  4644.      /* Line 16 --> User max d/l in k                                     */
  4645.      /* Line 17 --> User phone number                                     */
  4646.      /* Line 18 --> Time / date last call                                 */
  4647.      /* Line 19 --> Either NOVICE or EXPERT - user mode                   */
  4648.      /* Line 20 --> N=none, X=Xmodem, C=Xmodem/crc etc                    */
  4649.      /* Line 21 --> Last new file search MM/DD/YY                         */
  4650.      /* Line 22 --> User total number of call                             */
  4651.      /* Line 23 --> User line per page or screen                          */
  4652.      /* Line 24 --> Last msg no read                                      */
  4653.      /* Line 25 --> User total u/l since first log-on                     */
  4654.      /* Line 26 --> User total d/l since first log-on                     */
  4655.      /* Line 27 --> Either 7  {Databits} or 8  {Databits}                 */
  4656.      /* Line 28 --> Either LOCAL or REMOTE                                */
  4657.  
  4658.      /* Line 29 --> Comm port ID.                                         */
  4659.      /* Line 30 --> User birthdate                                        */
  4660.      /* Line 31 --> TRUE/FALSE                                            */
  4661.      /* Line 32 --> Normal connection                                     */
  4662.      /* Line 33 --> Time & Date door entered                              */
  4663.      /* Line 34 --> #                                                     */
  4664.      /* Line 35 --> Door id number                                        */
  4665.  
  4666.      The CALLINFO.BBS file is read in one line at a time and the information
  4667.      is stored  in the  appropriate  bbs_node  structure  field or  the user
  4668.      data structure.
  4669.  
  4670.                                                                         101
  4671.      /*
  4672.       *
  4673.       * GAP BBS DOOR.SYS file format
  4674.       *
  4675.       */
  4676.  
  4677.      /* Line  1 --> Comm port (COM0 = local)                              */
  4678.      /* Line  2 --> baud rate 300 - 38000                                 */
  4679.      /* Line  3 --> Parity 7 - 8                                          */
  4680.      /* Line  4 --> Node number 1 - 99                                    */
  4681.      /* Line  5 --> Host modem locked flag Y - N                          */
  4682.      /* Line  6 --> Screen display Y - N                                  */
  4683.      /* Line  7 --> Printer toggle Y - N                                  */
  4684.      /* Line  8 --> Page bell Y - N                                       */
  4685.      /* Line  9 --> Caller alarm Y - N                                    */
  4686.      /* Line 10 --> User full name                                        */
  4687.      /* Line 11 --> User city and state                                   */
  4688.      /* Line 12 --> Home phone number                                     */
  4689.      /* Line 13 --> Work/data phone number                                */
  4690.      /* Line 14 --> User password                                         */
  4691.      /* Line 15 --> User security level                                   */
  4692.      /* Line 16 --> Total times on BBS                                    */
  4693.      /* Line 17 --> Last date user called BBS                             */
  4694.      /* Line 18 --> Seconds remaining this call                           */
  4695.      /* Line 19 --> Minutes remaining this call                           */
  4696.      /* Line 20 --> Graphics mode GR, NG, 7E                              */
  4697.      /* Line 21 --> Page length                                           */
  4698.      /* Line 22 --> User expert flag Y - N                                */
  4699.      /* Line 23 --> Conferences registered in                             */
  4700.      /* Line 24 --> Conference exited door from                           */
  4701.      /* Line 25 --> User expiration date                                  */
  4702.      /* Line 26 --> Users file record number                              */
  4703.      /* Line 27 --> Default xfer protocol                                 */
  4704.      /* Line 28 --> Total uploads                                         */
  4705.      /* Line 29 --> Total downloads                                       */
  4706.      /* Line 30 --> Daily download K total                                */
  4707.      /* Line 31 --> Daily download max K                                  */
  4708.  
  4709.      The DOOR.SYS file is read  in one line at a time and the information is
  4710.      stored in  the appropriate  bbs_node structure  field or  the user data
  4711.      structure.
  4712.  
  4713.                                                                         102
  4714.      /*
  4715.       *
  4716.       * WWIV BBS CHAIN.TXT file format
  4717.       *
  4718.       */
  4719.  
  4720.      /* Line  1 --> User number                                           */
  4721.      /* Line  2 --> Users alias                                           */
  4722.      /* Line  3 --> Users real name                                       */
  4723.      /* Line  4 --> Amateur radio callsign                                */
  4724.      /* Line  5 --> Age                                                   */
  4725.      /* Line  6 --> Sex (M/F)                                             */
  4726.      /* Line  7 --> Gold (game credits)                                   */
  4727.      /* Line  8 --> Last date on BBS                                      */
  4728.      /* Line  9 --> Width of screen                                       */
  4729.      /* Line 10 --> Lines in screen                                       */
  4730.      /* Line 11 --> Security level                                        */
  4731.      /* Line 12 --> SysOp flag                                            */
  4732.      /* Line 13 --> Co-SysOp flag                                         */
  4733.      /* Line 14 --> ANSI graphics flag                                    */
  4734.      /* Line 15 --> Remote user flag                                      */
  4735.      /* Line 16 --> Time remaining in seconds (float)                     */
  4736.      /* Line 17 --> General text file directory                           */
  4737.      /* Line 18 --> Data file directory                                   */
  4738.      /* Line 19 --> Path/Filename for text sysop log                      */
  4739.      /* Line 20 --> Current baud rate (KB = local)                        */
  4740.      /* Line 21 --> Comm port number                                      */
  4741.  
  4742.      The CHAIN.TXT file is read in one line at a time and the information is
  4743.      stored in  the appropriate  bbs_node structure  field or  the user data
  4744.      structure.
  4745.  
  4746.                                                                         103
  4747.      /*
  4748.       *
  4749.       * Time control structures
  4750.       *
  4751.       */
  4752.  
  4753.      struct bbs_access                       /* TIME OPTION INFORMATION   */
  4754.      {
  4755.        long start_time;                      /* Start of game period      */
  4756.        int  levels[8];                       /* Play times per level      */
  4757.      };
  4758.  
  4759.      The bbs_access structure contains  time limits for each access level by
  4760.      start time.
  4761.  
  4762.  
  4763.      struct bbs_time                          /* TIME OPTION INFORMATION   */
  4764.      {
  4765.        long sysop_start;                      /* SysOp starting time       */
  4766.        long sysop_stop;                       /* SysOp ending time         */
  4767.        int  levels[8];                        /* Security levels           */
  4768.        int  dayt[8];                          /* Daily time limits         */
  4769.        int  dayg[8];                          /* Daily game limits         */
  4770.        int  wait[8];                          /* Time between games        */
  4771.        struct bbs_access access[8];           /* Times for play            */
  4772.      };
  4773.  
  4774.      The bbs_time  structure contains  the information read  in from the time
  4775.      control  file  (times.DEF).    It  is  used  by  the  TIME_CONTROLS  and
  4776.      DAILY_CONTROLS functions  to determine if the user may validly enter the
  4777.      door application.
  4778.  
  4779.  
  4780.                                                                         104
  4781.      /*
  4782.       *
  4783.       * Global Data Section
  4784.       *
  4785.       */
  4786.  
  4787.  
  4788.      /* Remote User Data */
  4789.  
  4790.      FILE    *remote_io;                      /* Comm port stream          */
  4791.      int     remote_user;                     /* Comm port number          */
  4792.  
  4793.      The remote user data controls the virtual I/O  in the library functions.
  4794.      The remote_io file descriptor  is no longer used.   The remote user data
  4795.      reflects the comm port number or contains 0 if running local.
  4796.  
  4797.      The application program may wish  to control certain operations based on
  4798.      on the contents of this flag (ie. only output a bulletin file if running
  4799.      remotely).
  4800.  
  4801.  
  4802.      /* BBS Data */
  4803.  
  4804.      int     bbs_active;                      /* BBS active                */
  4805.      char    bbs_dir[];                       /* BBS home directory        */
  4806.  
  4807.      struct  bbs_node        bbs_node_info;   /* BBS node information      */
  4808.      struct  bbs_user        bbs_user_info;   /* BBS user information      */
  4809.      struct  pcbbs_data      pcbbs_user_info; /* PCBoard user information  */
  4810.      char    ascii_user_info[35][128];        /* ASCII based user info     */
  4811.      struct  bbs_time        bbs_time_info;   /* BBS time information      */
  4812.  
  4813.  
  4814.      The above  storage reflects the previously  defined data structures  and
  4815.      character arrays for reading the BBS text files.
  4816.  
  4817.  
  4818.                                                                         105
  4819.      /*
  4820.       *
  4821.       * Monitor Data Strutures
  4822.       *
  4823.       */
  4824.  
  4825.      FILE    *mon_inp;                        /* Input parameters          */
  4826.      FILE    *mon_out;                        /* Output parameters         */
  4827.      int     mon_active;                      /* Monitor active            */
  4828.  
  4829.      long    mon_signoff;                     /* time to signoff at        */
  4830.      int     mon_user;                        /* monitor user #            */
  4831.      int     mon_points;                      /* current player score      */
  4832.      int     mon_max_play;                    /* time to play in mins      */
  4833.      int     mon_nulls;                       /* number of nulls required  */
  4834.      int     mon_graphics;                    /* monitor graphics flag     */
  4835.      char    mon_dir[40];                     /* monitor subdirectory      */
  4836.      char    mon_sound[];                     /* monitor sound flag        */
  4837.  
  4838.  
  4839.      The  monitor data structures are used  as interim locations  to read the
  4840.      information provided in the monitor files TIMEOFFx.DOR and NAMES.DOR.
  4841.  
  4842.      This information is processed and stored in the appropriate bbs_node
  4843.      fields and the user data structures.
  4844.  
  4845.  
  4846.                                                                         106
  4847.  
  4848.      User Data Structures
  4849.      --------------------
  4850.  
  4851.      This  section will describe  the user control data structures.   These
  4852.      data structures have a major influence in controlling the time control
  4853.      functions and the virtual I/O functions.
  4854.  
  4855.      /*
  4856.       *
  4857.       * User Data Strutures
  4858.       *
  4859.       */
  4860.  
  4861.      int     user_node;                       /* users node                */
  4862.      char    user_name[32];                   /* users name                */
  4863.      char    user_game_date[12];              /* last day user player      */
  4864.      long    user_game_end;                   /* last time user played     */
  4865.      long    user_day_time;                   /* time user played          */
  4866.      int     user_day_games;                  /* games user played         */
  4867.      long    user_start;                      /* time user started game    */
  4868.      long    user_signon;                     /* time user signed on       */
  4869.      long    user_signoff;                    /* time to signoff at        */
  4870.      int     user_points;                     /* current player score      */
  4871.      int     user_security;                   /* number of nulls required  */
  4872.      int     user_nulls;                      /* number of nulls required  */
  4873.      int     user_graphics;                   /* graphics flag             */
  4874.      int     user_caps;                       /* caps only flag            */
  4875.      int     user_page;                       /* user page length          */
  4876.      int     user_access_level;               /* user game access level    */
  4877.  
  4878.  
  4879.      The  user data structures have  the greatest effect  on the operation of
  4880.      the  DM library funtions.   The user_node  and user_name values are used
  4881.      primarily as reference items.
  4882.  
  4883.      The user_game_date, user_game_end, user_day_time,  user_day games fields
  4884.      are related to the time controls provided by the DM library.   It is the
  4885.      responsibility of the application to fill in these fields.
  4886.  
  4887.      The user_start,  user_signon,  and user_signoff fields  are filled in by
  4888.      the various BBS access functions and may be modified by the time control
  4889.      functions.  The user_signoff field may be modified by the application if
  4890.      the  application wishes  to set up its  own time controls above those in
  4891.      the DM library.   For instance  an application could guarantee a maximum
  4892.      of a 30 minute session using the following code example:
  4893.  
  4894.         if((user_signoff - user_signon) > 1800L)
  4895.           user_signoff = user_signon + 1800L;
  4896.  
  4897.      This should be performed after the BBS access functions have been called
  4898.      or it will have no effect.
  4899.  
  4900.      The  user_security and  user_access_level are  used  by  the library for
  4901.      the time control functions.
  4902.  
  4903.      The user_nulls, user_graphics,  user_caps, and user_page values are used
  4904.      by  the virtual I/O functions and  control things such as metered output,
  4905.      ANSI sequencing for clearing the display and positioning the cursor, and
  4906.      filtering of I/O characters.
  4907.  
  4908.  
  4909.                                                                         107
  4910.  
  4911.      In Closing
  4912.      ----------
  4913.  
  4914.      In closing,  let me say that I hope this library  is of help to writing
  4915.      your door applications.   If you have any difficulties or would like to
  4916.      report any bugs,  please leave mail for the SysOp on my system,  or you
  4917.      may send information by mail to:
  4918.  
  4919.                            Mycroft RBBS
  4920.                            c/o Michael W. Bayley
  4921.                            P.O. Box 7672
  4922.                            San Jose, Ca. 95150-7672
  4923.                            (408)927-0105
  4924.  
  4925.  
  4926.  
  4927.